Why the $content_width WordPress setting hurts optimization.

There is this somewhat mysterious $content_width GLOBAL in WordPress that effects many themes, including all the WordPress releases (Twenty Ten, Twenty Eleven, Twenty Twelve).

So what does this global setting do?

It  sets a limit on the image width when you insert images into a post AND overwrite’s any setting in the Media section that are set to a larger size then itself. It also sets the width limits on embeds such as YouTube videos.

Example of how it is added to a theme (Twenty Twelve):

// sets max image width inserted into a post
if ( ! isset( $content_width ) )
 $content_width = 584;

Why does it kinda suck?

Two reasons, it overrides users control which can cause confusion and it re-sizes images via HTML, let’s dig in with an example.

Testing a dummy.jpg uploaded into WordPress with default settings (large image set to 1024 x 1024) :

Original Image stats:

  • 3465 x 2304
  • 1.27MB

Inserting the image into a post by clicking “Large” results in this output.

<a href=".../wp-content/uploads/2013/02/IMG_1390.jpg"><img alt="IMG_1390" src="..../wp-content/uploads/2013/02/IMG_1390-1024x682.jpg" width="584" height="328" />

The image size loaded in the browser is 194.87KB yet it’s only 584px wide, hmm…??

If instead we remove this GLOBAL setting and set the image to the size we actually want, in this case let’s just set a custom add_image_size to max 600px width but still link to the larger size, the output is:

<a href="...../wp-content/uploads/2013/02/IMG_13901.jpg"><img alt="IMG_1390" src="......t/wp-content/uploads/2013/02/IMG_13901-600x600.jpg"width="600" height="400" />

So now we re-load the page and the image is 79.27KB, a saving of 116KB ! One can only imagine how much this saves on posts with multiple images.

It’s also confusing to look at, with the GLOBAL set the dropdown looks like this.


When it should look like this:


Of course the reason for having it is so users don’t click the wrong size and break the layout of their websites, but it seems silly to do it via HTML. You’re getting the benefit of design consistency but loose out on speed.

If you must contain the image proportions then why not just use CSS? There is not difference in speed when containing images in HTML vs CSS, but the added benefit of doing it via CSS is that at least you will load the more optimized image and it’s easier to manipulate for responsive layouts.

The problem is confounded because this Global settings is used by many plugins, and is a requirement for any themes submitted to wordpress.org.

I’m not 100% sure what a good way around this is, I asked the question on WPSE and so far all I can come up with is hijacking the insert function to prevent full image sizes and instead limiting the user with add_image_size , something like this gist


5 thoughts on “Why the $content_width WordPress setting hurts optimization.

  1. Thanks for explaining this. I was very confused using this global variable. I see it in every default themes, but actually don’t use it at all. It seems redundant, or at least not useful to users. I think WP should have better method controlling max width of image, maybe via a setting in Media page.

  2. Gosh, I have been trying to figure out for hours why my large image size would not exceed 640px and then I found that $content_width was overriding the specified value under media settings!

    I had added $content_width to make sure Youtube would span the whole width of the content area, but now I am doing this using css (it blows up the iframe that is 500px wide to 640px, but it fortunately still looks ok).

    I would love to see something like $embed_width introduced to overcome this. (Wrapping the Youtube link with is unfortunately too difficult for most content editors.

  3. I am still a little confused about this.
    Because this global is required when submitting themes to wordpress.org, we do need to actually use this. But if it’s causing issues, why can’t I just set the max width to a really large number and make sure I have a good array of image sizes available to use? I would need to include css to make sure images don’t overflow the content areas, but that’s fine.
    I’m sure there will be a reason that I shouldn’t just set this to be a hige number, but I just can’t get my head around it. Can anyone help me?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s