WordPress gives you several ways to control an oEmbed’s dimensions, depending on where the embed is created and when you need to change it. Use embed_defaults for site-wide defaults, pass width and height to wp_oembed_get() for one programmatic embed, use oembed_result to normalize provider HTML before it is cached, or use embed_oembed_html to alter cached markup while it is rendered. Because the external provider decides how to interpret requested dimensions, responsive CSS is usually the final layer.
Which WordPress dimension method should you use?
| Method | Scope | When it runs | Does the provider receive dimensions? | Typical use |
|---|---|---|---|---|
embed_defaults |
Global defaults | Before an embed request is made | Yes, through the resulting request | One standard size across the site |
wp_oembed_get() |
One retrieval call or URL | When your code fetches the embed | Yes, as maxwidth and maxheight |
Different sizes in templates or plugins |
oembed_result |
Returned provider HTML | Before WordPress caches the result | The request has already been made | Consistent markup normalization |
embed_oembed_html |
Rendered cached output | During page rendering | No new provider request | Adjusting existing cached embeds |
REST maxwidth/maxheight |
One REST consumer request | At the oEmbed REST endpoint | Yes, through WordPress’s fetch logic | Another application consuming WordPress oEmbed data |
Choose the earliest hook that matches your need. A render-time filter can fix output already in the cache, but it may execute repeatedly on page loads; a retrieval-time solution is generally cleaner when you control the original call.
Set a site-wide default width and height
WordPress derives its default width from the global content width when one is available; otherwise the fallback width is 500px. The default height is the smaller of 1.5 times the width or 1000px. Override both values with the embed_defaults filter:
add_filter( 'embed_defaults', function ( $size, $url ) {
return array(
'width' => 800,
'height' => 450,
);
}, 10, 2 );The $url argument lets you make the default conditional if necessary, although a single pair is usually easier to maintain. Put this code in a site-specific plugin or your child theme rather than editing WordPress core.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Set dimensions for one programmatic embed
If a plugin or template calls wp_oembed_get(), pass dimensions in that call. This keeps one URL independent from the site-wide default:
$html = wp_oembed_get(
'https://www.youtube.com/watch?v=VIDEO_ID',
array(
'width' => 800,
'height' => 450,
)
);WordPress forwards these values to the provider as maxwidth and maxheight. They are requested maxima, not a guarantee that the returned iframe or other markup will use exactly those dimensions.
Change provider HTML before it is cached
The oembed_result filter receives the provider’s HTML, the source URL, and the request arguments before WordPress stores the result in its oEmbed cache. It is useful for applying a consistent wrapper or provider-specific transformation:
Rank #2
add_filter( 'oembed_result', function ( $html, $url, $args ) {
if ( false !== strpos( $url, 'youtube.com' ) ) {
$html = '<div class="video-embed">' . $html . '</div>';
}
return $html;
}, 10, 3 );A wrapper does not itself force a fixed iframe size. Add CSS or carefully modify attributes and styles only after checking the markup that the provider returns. Restrict transformations by provider or URL so unrelated embeds are not altered.
Change cached output while WordPress renders it
Use embed_oembed_html when the embed has already been retrieved and cached, or when you cannot change the code that made the original request. The filter receives cached HTML, the URL, shortcode attributes, and the post ID:
add_filter( 'embed_oembed_html', function ( $cache, $url, $attr, $post_id ) {
return '<div class="responsive-oembed">' . $cache . '</div>';
}, 10, 4 );This runs during page rendering and can run repeatedly, so avoid expensive parsing or network work in the callback. If you need the same transformation for newly fetched results, oembed_result is earlier in the lifecycle and avoids doing the work on every render.
Rank #3
Request a custom size through the oEmbed REST endpoint
Applications consuming WordPress’s oEmbed REST API can send maxwidth and maxheight parameters:
/wp-json/oembed/1.0/proxy?url=https%3A%2F%2Fexample.com%2Fpost&format=json&maxwidth=800&maxheight=450The REST controller copies these values into the arguments used by WordPress’s fetch logic. Its oembed_default_width setting defaults to 600. For WordPress’s first-party REST response path, requested width is constrained to a 200–600px range, and the response height is calculated from a 16:9 ratio with a 200px minimum. Those limits apply to that response path, not necessarily to every provider or front-end embed.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchMake embeds responsive with CSS
Provider markup can include intrinsic iframe or video dimensions. A wrapper lets the element follow its container:
.responsive-oembed {
max-width: 100%;
aspect-ratio: 16 / 9;
overflow: hidden;
}
.responsive-oembed iframe,
.responsive-oembed video {
width: 100%;
height: 100%;
border: 0;
}A 16:9 ratio suits many videos but is not universal. Inspect the actual provider output before imposing it; podcasts, documents, image embeds, and some video players use different proportions. For content that should preserve its natural ratio, use provider-specific classes or a height strategy based on the returned markup. WordPress core also uses max-width: 100% and height: auto in responsive-content handling, but provider responses vary.
Why a requested width or height is ignored
The provider treats the values as maximums
WordPress sends maxwidth and maxheight, not an order to emit exact dimensions. A provider can ignore, cap, or reinterpret them.
The cached result predates your change
Changing a filter does not necessarily rewrite an existing cached response. Purge the relevant oEmbed or page cache, or use a render-time filter when you must adjust already cached HTML.
CSS overrides the inline or intrinsic size
Theme rules, block styles, and iframe attributes can conflict. Inspect the element in browser developer tools, identify the rule winning in the cascade, and apply the responsive wrapper or a narrowly scoped selector.
The REST endpoint has its own bounds
A REST consumer may receive the endpoint’s width and height constraints even when a larger value was requested. Treat the returned dimensions as endpoint-specific.
The provider is not fully supported
WordPress’s automatic discovery for non-whitelisted providers has documented limitations. A URL may therefore return different markup or no embed at all, regardless of your requested dimensions.
Provider-specific dimensions are not WordPress-wide rules
WordPress.com documents image defaults of 440×330px and an img_size width-by-height alternative for its provider API. Those are provider-specific API behaviors; do not use them as defaults for YouTube or every other oEmbed service.
Free tools Windows power users keep installed
One-click scans. No signup required.
Quick Recap
A practical implementation checklist
- Decide whether the size is global, per URL, per post, or controlled by an external REST consumer.
- Use
embed_defaultsfor a global pair orwp_oembed_get()arguments for a specific retrieval. - Use
oembed_resultwhen you need to normalize newly fetched provider HTML before caching. - Use
embed_oembed_htmlonly when cached output must be changed at render time. - Add a wrapper and responsive CSS when the embed must fit fluid layouts.
- Test the actual provider response at desktop and mobile widths, then clear relevant caches after code changes.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
