WordPress gives you four practical places to control an oEmbed’s dimensions: set site-wide defaults with embed_defaults, pass dimensions to a specific wp_oembed_get() call, alter provider HTML before it is cached with oembed_result, or adjust cached markup while it renders with embed_oembed_html. Because the provider ultimately generates the embed code, finish with responsive CSS when the iframe or video must follow its container.
Choose the control point that matches your embed
| Method | Scope | Lifecycle point | Are dimensions sent to the provider? | Best use |
|---|---|---|---|---|
embed_defaults |
All standard embeds using the defaults | Before retrieval | Yes, as maxwidth and maxheight |
A consistent site-wide starting size |
wp_oembed_get() arguments |
One programmatic URL at a time | During that retrieval call | Yes | Templates or plugins that own the request |
oembed_result |
Returned provider HTML, commonly by URL or provider | Before WordPress caches the result | The request has already been made | Normalizing markup before it enters the cache |
embed_oembed_html |
Rendered cached output | During page rendering | No new provider request | Changing existing cached output without controlling retrieval |
REST maxwidth/maxheight |
Clients consuming WordPress’s oEmbed endpoint | At the REST request | WordPress forwards the values to its fetch logic | An external application requesting a particular size |
Set a site-wide default size
WordPress derives its default width from the global content width when one is available; otherwise the fallback is 500px. The default height is the smaller of 1.5 times the width or 1000px. Override both values with the embed_defaults filter in a plugin or a site-specific theme file:
add_filter( 'embed_defaults', function ( $size, $url ) {
return array(
'width' => 800,
'height' => 450,
);
}, 10, 2 );This changes the default pair used by WordPress; it does not force every provider to emit an 800-by-450 iframe. Provider markup and its own limits still apply.
Set dimensions for one programmatic embed
When your plugin or template calls wp_oembed_get(), pass dimensions in the second argument:
Free tools Windows power users keep installed
One-click scans. No signup required.
$html = wp_oembed_get(
'https://www.youtube.com/watch?v=VIDEO_ID',
array(
'width' => 800,
'height' => 450,
)
);WordPress sends these requested values to the provider as maxwidth and maxheight. This is the clearest choice when different URLs need different sizes and your code controls the retrieval call.
Alter provider HTML before it is cached
The oembed_result filter receives the provider’s HTML, the requested URL and the arguments. It runs before WordPress stores the result in its oEmbed cache, so it is suitable for consistent, provider-specific normalization:
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 );The wrapper alone does not impose a fixed iframe size. Add CSS or a carefully targeted transformation for the actual markup returned by that provider. Restrict URL tests and transformations narrowly so unrelated providers are not changed.
Rank #2
Change cached output while it renders
embed_oembed_html runs after retrieval, receiving cached HTML, the URL, shortcode attributes and the post ID:
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →add_filter( 'embed_oembed_html', function ( $cache, $url, $attr, $post_id ) {
return '<div class="responsive-oembed">' . $cache . '</div>';
}, 10, 4 );Use this when existing cached output must be wrapped or replaced and you cannot control the original request. Because it can run on page loads, avoid expensive parsing or broad processing in this filter.
Request dimensions through the oEmbed REST endpoint
An external client can request dimensions from WordPress’s oEmbed proxy by supplying maxwidth and maxheight:
Rank #3
/wp-json/oembed/1.0/proxy?url=https%3A%2F%2Fexample.com%2Fpost&format=json&maxwidth=800&maxheight=450The REST controller copies those values into the width and height arguments used by WordPress’s fetch logic. Its first-party response path has additional bounds: requested width is clamped to a default 200–600 range, and the response height is calculated from a 16:9 ratio with a 200px minimum. Treat those limits as specific to this WordPress REST response path, not as universal provider rules. The controller’s oembed_default_width default is 600.
Make the rendered embed responsive with CSS
Requested dimensions describe the retrieval, while the provider controls the returned HTML. A wrapper gives your layout a reliable front-end constraint:
.responsive-oembed {
max-width: 100%;
aspect-ratio: 16 / 9;
overflow: hidden;
}
.responsive-oembed iframe,
.responsive-oembed video {
width: 100%;
height: 100%;
border: 0;
}Apply the class to the wrapper produced by either PHP filter. This 16:9 rule is appropriate only when the provider’s content has that shape; test the actual provider response before enforcing it. For content with an intrinsic or variable ratio, use a provider-appropriate ratio or let the element determine its height. WordPress core also uses max-width: 100%; height: auto; patterns for responsive content, but provider responses vary.
Why an oEmbed may ignore your width or height
The provider treats values as maximums
WordPress sends maxwidth and maxheight, not a promise that the provider must use those exact dimensions. A provider can ignore, cap or reinterpret them.
You changed the wrong lifecycle stage
embed_defaults and wp_oembed_get() affect retrieval arguments. oembed_result changes HTML before caching, while embed_oembed_html changes cached HTML at render time. Pick the stage that matches whether the problem is the request, the cached result or the final layout.
CSS is overriding the inline or intrinsic size
Even correctly generated markup can overflow a narrow column. Inspect the iframe or video in the browser, then apply a scoped wrapper rule rather than globally forcing every iframe on the site.
Cached markup is still being served
If you change a pre-cache filter, previously stored results may continue to render until the relevant oEmbed cache is refreshed. A render-time filter is useful when you need the change to apply to existing cached output.
Implementation checklist
- Use
embed_defaultsfor a single site-wide default pair. - Use
wp_oembed_get()arguments when each programmatic URL needs its own request size. - Use
oembed_resultto normalize provider HTML before it is cached. - Use
embed_oembed_htmlfor render-time changes to cached output, keeping processing light. - Use REST
maxwidthandmaxheightwhen another application consumes WordPress’s oEmbed proxy. - Inspect provider markup and add scoped responsive CSS whenever the embed must fit a fluid container.
Provider-specific exceptions
oEmbed behavior is not uniform. Discovery for non-whitelisted providers has documented limitations, and each provider can generate different markup or enforce different dimensions. WordPress.com’s provider API, for example, documents image defaults of 440×330px and an img_size width-by-height alternative; those values apply to that provider API and should not be generalized to YouTube or other services.
Quick Recap
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.
