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.
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
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 jond3r.org 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.
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_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.
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_ function, which in turn makes use of
image_constrain_ to get the possibly constrained image sizes. Note that only the standard image sizes, i.e.
'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
According to the
image_ 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.
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).