How images are constrained in size when inserted in the WordPress editor

The article describes how images are constrained in size when inserted in the editor in WordPress, and the role of the variable $content_width. Under certain conditions even thumbnails and medium-sized images are constrained.

In WordPress 3.5 a significant update was made to the media administration panels, which now rely heavily on JavaScript and the Backbone.js framework.

A not very obvious fact is that images are sometimes constrained in size when inserted in a post, which means that their height and width attributes are reduced compared to the actual image size. This is generally done to make the images fit the main content area of the post or page.

This post is about a small detail of the media insertion panel, namely the calculation of the image dimensions shown in the size drop-down list for a selected image in the panel, and which are applied to the inserted image. I contributed with some bug fixes to the image size calculations (tickets #22738 and #23102). Ticket #22738 made a correction to the shown dimensions of large-size images, which are likely to be constrained in size due to the $content_width variable. Ticket #23102 provided a similar fix for thumbnails and medium-sized images, which in some circumstances also are constrained in size.

A constrained large-size image
A large-size image constrained to 704px, and with a max-width of 100%

Making images fit the width of the main content area

A theme may set the global PHP variable $content_width, to indicate the width of the main content of a post or page. This variable is then used in WordPress core to constrain the size of images to fit the main content area. This happens in the function image_constrain_size_for_editor().

Not all themes have a fixed content width though. For example some themes may use a fluid layout or some other responsive technique to adapt the theme to the width of the browser window. In those cases it is not possible to set a fixed content width that is always representative of the actual content width. However, by giving images the CSS property max-width a value of 100 % they will not overflow the content area.

The current theme on uses a fluid layout, and the $content_width is set to 704 pixels, which is the maximum width of the main content area. As the browser window is made narrower, the actual content width decreases (to a certain extent), but thanks to the fact that figure and image elements have a max-width of 100%, they do not overflow the main content area (observe the large-size image above as the browser width is varied).

Where in WordPress core the image dimensions are calculated

Most WordPress core functions that need to output HTML of an image tag make use of the image_downsize() function to get the image source, width and height attributes. This applies to e.g. get_image_tag() and wp_get_attachment_image().

In those cases when you have the image size name, and just want to know the size of the (possibly constrained) image, you can instead use the image_constrain_size_for_editor() function. As a part of its processing, image_downsize() calls image_constrain_size_for_editor(), but the overhead in image_downsize() is significant. It is on average up to 22 times slower than image_constrain_size_for_editor() as shown in #23102.

The size drop-down
The size drop-down list showing a constrained large size and a custom size 'MyTheme'

To get the available image sizes for the size drop-down list in the sidebar of the Insert Media panel (see left), WordPress core uses the wp_prepare_attachment_for_js() function, which in turn makes use of image_constrain_size_for_editor() to get the possibly constrained image sizes. Note that only the standard image sizes, i.e. 'thumbnail', 'medium' and 'large', in addition to the full size image, are by default considered for inclusion in the drop-down. However, there is a filter 'image_size_names_choose' available for adding custom image sizes (and removing the standard ones).

Possible types of image constraint

The Media Settings panel
The Media Settings administration panel

According to the image_constrain_size_for_editor() function, the three standard image sizes are constrained by the current size settings in the Media Settings administration panel (see right). Thus if these settings have been reduced between image upload and insertion, the inserted image will be constrained. This happened to the medium-size image below, which has an uploaded default width of 300 px, but is constrained to 200 px on insertion due to a reduction in the Medium size setting to 200 px.

A constrained medium-size image
Medium size image constrained to 200px

Large-size images are then further constrained by the $content_width variable. This is the most likely constraint to take place, since large-size images are by default 1000 px wide and $content_width is generally smaller.

Custom image sizes (as defined by a theme or plugin calling add_image_size()), are also constrained by $content_width, but only in the context of 'edit', i.e. on admin pages in general. Full-size images are never constrained.

The size drop-down list depicted above, shows default thumbnail and medium sizes, a large size constrained to 704 px, the full size and a custom size called 'MyTheme' (which is not constrained).

Posted in WordPress Dev Tags: , , RSS feed for comments on this post Send trackbacks to:

Comments section


  • Avatar of Johnk248


    I've been absent for a while, but now I remember why I used to love this site. Thank you, I'll try and check back more frequently. How frequently you update your site?

    reply »

Leave a reply


(required) (not published or shared)

Allowed tags:

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>