Simon Garrett

WordPress content width and alignment – lack of documentation

17th August 2024
Rev 24th October 2024

WordPress Block Themes and Full Site Editing greatly increase the power and flexibility for the user.

The architecture has been evolving rapidly, and there are a few rough edges, which is perhaps to be expected. The documentation has not always kept pace.  For example, documentation of block width and block alignment is incomplete and sometimes misleading.  Forum posts include numerous posts asking about apparently bizarre misalignment between different blocks. Answers are sometimes incomplete, offer CSS hacks or are just plain wrong, but almost never explain what’s actually happening. 

I’ve written below about one set of topics (block width and alignment) where the existing documentation is incomplete to the point of (in my view) being misleading.  My own understanding might be incomplete – even wrong – and what follows isn’t intended to provide the missing documentation (and it’s too brief), but it’s an outline of the some of the issues missing in existing WordPress.org documentation.  Illustrations and examples would be needed too.

What is needed is a better overview documentation of:

  • the three widths available to blocks, how they are defined and inherited
  • how the Align parameter works, as it combines multiple functions
  • the Layout parameter in container blocks, and the full impact it has on inner blocks

Worked examples should be included. 

Summary

There are generally three possible widths a block may occupy: Content (width), Wide (width), and Container width.  The latter is defaulted and set quite differently to the first two. 

Content and Wide widths for blocks

  • Global default set in theme.json
  • Default can be overridden globally in Styles book -> Layout
  • Can never be larger than the block’s container width, and Content can’t be greater than Wide. 
  • Can be set locally in the block’s container block:
    • If the container block’s Layout -> Inner blocks use content width param is on:
      • If the associated params are left blank then the global values are used (which could be larger or smaller than the values in an outer block, but might be reduced by padding, I don’t fully understand this latter point)
      • If the associated params are set, these values are used (again, can be larger or smaller than the values in an outer block, but not larger than the container width)
    • If the container block’s Layout -> Inner blocks use content width param is off, then Content and Wide are set to the container width (and the block will not allow width to be set in the Align param).

Container width of a container block

  • Can’t be greater than the parent container width
  • If the parent container’s Layout -> Inner blocks use content width param is on:
    • The container will have an Align parameter, and can set container width to “None” aka Content width (this is the default), “Wide” of “Full width” width set by parent container.
    • NB the Content and Wide values are those set or implied by the parent’s Layout -> Inner blocks use content width param, not the global values.
  • If the parent’s Layout -> Inner blocks use content width param is off then the container block has container width set to the parent’s container width (and the local default Content and Wide are also set to parent container width).  In this case the container block won’t have an Align param (or if present, it won’t allow container width to be set).   

In detail – Widths and alignment

Block width(s)

There are three defined widths that most blocks can use, depending on the context:

  • “Content”, confusingly described in settings as “None”
  • “Wide”
  • “Container width”, also referred to as “full width” in settings

In any block, Wide width can’t be greater than Container width, Content width can’t be greater than Wide width.

Paragraph blocks use only Content width, but many blocks can use all three, selected by the Align setting on the toolbar for the block. 

Both “Content” and “Wide” are described in documentation, but “Container width” is little mentioned in the same context.  In addition, Container width is set and inherited rather differently from the other two. 

Content and Wide widths are default to the setting by the theme (for block themes in themes.json, but can be overridden in Styles -> Layout).  They can be set in individual container blocks in Layout settings if “Inner blocks use content width” is checked (on).  Content and Wide can be larger or smaller in a child container than in the parent container, but never larger than the Container width. 

That is, the actual setting of Content and Wide widths depends on whether the Layout parameter “Inner blocks use content width” is “on” in the parent container, and whether width numbers are given in the Layout parameter (or left blank).  If it is “off”, then both Content and Wide width are set to the parent container width, not the theme.json values.

Container width typically starts (at the outermost container block in the template) at full width of the browser (or phone) window.  For any child container (or grand child etc), the container inherits the container width of its parent, but can override that by the Align setting in the toolbar.  Precise behaviour depends on whether the Layout parameter “Inner blocks use content width” is “on” in the container’s parent container (note: the container’s parent, not the container itself) . 

  • If “Inner blocks use content width” is “off” in the parent container, then the container itself does not have an Align setting, and the container inherits the parent’s container width (and defaults Content and Wide widths set to container width as well). Note that although it can’t alter the container width passed down to child blocks, it can alter the Content and Wide widths passed down to child blocks by setting “Inner blocks use content width” to “on” in the container block itself (not its parent container).
  • If “Inner blocks use content width” is “on” in the container’s parent container, then the container width in a container block (Group, Row, Stack, Columns etc) is set by the container’s Align setting in the toolbar. It can also alter the Content and Wide width by setting “Inner blocks use content width” to “on”, just as in the previous paragraph, but not to values greater than the chosen container width.

If “Inner blocks use content width” is “on” in the container’s parent container, then the container’s toolbar will have an Align setting to set the container’s container width, and the choice is:

  • “None” (which means use the inherited Content width). This is the default.
  • “Wide” (as inherited).
  • “Full width” (which means the inherited container width). 

This means that in any container, the container width can be the same as or smaller than the parent container (but not larger, logically enough).  Note that this is different to the options for Content and Wide widths, which can be larger than the parent’s settings. 

Note that the default setting in the Align setting in a container block is “None”, that is use inherited Content width for Container width.  This means that the default for any new container is that the Container width, Content width and Wide width are all the same, taking the value of the inherited Content width.  I’ve emphasised this as although this default is probably the most useful choice, it’s also probably not what one would expect!

Remember also that it depends on the setting of “Inner blocks use content width” in the container’s parent container. This means that container width seen by (for example) an image block may depend not only on the image block’s parent container, but parent container’s parent container!

“Inner blocks use content width”

This setting is in the Layout section of most container blocks, and it’s crucial to the content and wide widths available to inner blocks:

On: nested block use content width (and wide width) either default (e.g. from theme.json as altered in Dashboard -> Appearance -> Editor -> Styles -> Layout) or with settings under “Inner blocks use content width”

Off: nested blocks will fill the width of this container.  That is, Content and Wide widths are the same as the inherited container width. 

The container width inherited by inner blocks depends on the setting of the container block’s Align parameter, if it has one (it won’t if its parent has its “Inner blocks use content width” off.

The Align setting

Many blocks have an “Align” setting on the toolbar.  This setting is heavily overloaded, and is used for multiple purposes, depending on the block, including:

  1. To set the block width.  Choices are usually “Content width” (confusingly described as “None”), “Wide” or “Full-width” (meaning: container width).
  2. To set alignment within the block width (e.g. left, right or centre). This is what the Paragraph block uses the Align setting for.
  3. To turn on or off image stretch (e.g. normal size or stretched to fill the width)
  4. To turn on or off text wrap around an image
  5. In Container blocks, to set Container width.

In some blocks, different uses are combined.  For example, in the Image block, when you choose “Align Left”, it does two things: it turns on text wrap around the image, but it also sets the width to Container width instead of Content width.  This is not documented. 

The other surprise: the “Align” setting isn’t always present in the block toolbar, or if present some of the options may not always appear.  If a container block’s parent container has “Inner blocks use content width” turned off, then the container cannot alter its width and may not have the Align setting.  Similarly, for any block type, if the Content width is the same as container width, any Align options to alter width won’t show, and if there are no other Align options then the Align setting doesn’t appear. 

Example of potential user confusion from lack of comprehensive documentation

The ambiguity of the Align setting and its poor documentation, and the lack of complete descriptions of how Container width is set and inherited, lead to surprising behaviour at times. 

An example of this is when trying to align Image blocks with Paragraph blocks. 

Many themes such as Twenty Twenty-Four have a default Content width significantly narrower than typical browser window size (except on a phone).  For Twenty Twenty-Four, the default Content width is 620 pixels. This means that a column of text in a Paragraph block (which always uses Content width) is often relatively narrow within the browser window.  Place an image next to a Paragraph block, and at default settings it too uses Content width, so aligns with text.

Here’s an example:

But change the image to “Align left”, which makes the text wrap around the image, and suddenly the image whizzes off to the left of the screen! 

Why?

Google for an explanation, and you find answers suggest putting a Group block around the image.  Do this and the image now aligns with the text. 

But why?

The reason is that the Image block uses Content width by default (and aligns with a Paragraph block, which always uses Content width).  However, when you select “Align left” in the Image block, it not only aligns left and wraps text around the image, but also changes the width from Content width to Container width. In many themes I’ve tried, the outermost block on the page inherits a Container width set to full width of the browser window, so the image moves to the left of the window.  Create a new Group block, and at default settings, the new Group block sets the Container width to the same as Content width (as explained above).  When you put the image inside it, with “Align left” it uses the Container width, which is now the same as Content width, and the same as the text.  Now the image aligns with the text. 

This behaviour – images with “Align left” aligning with text only if Content width is the same as Container width, and why this happens automatically when a child Group block is created – is not documented anywhere I can find on wordpress.org.