17th August 2024
WordPress Block Themes and Full Site Editing greatly increase the power and flexibility for the user. I love the new opportunities it gives; I’ve converted most of the live sites I manage from legacy themes to block themes (and created one or two new ones).
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 suggest I’m not alone in thinking this. There are 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 giving an incorrect view. 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.
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
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 barely mentioned. In addition, Container width is set and inherited rather differently from the other two.
Content and Wide widths are usually set by the theme (for block themes in themes.json, and can be overridden in Styles -> Layout). They can be set in individual container blocks in Layout settings. Default values are inherited from the block’s parent container block, and both Content and Wide can be larger or smaller in a child container than in the parent container, but never larger than the Container width. The actual setting and inheritance behaviour 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).
Container width typically starts (at the outermost container block in the template) at full width of the browser 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 inherits Content and Wide widths 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.
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 conainer 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!
This is rather complicated, but it has a certain logic to it. What it doesn’t have is complete documentation.
The Align setting
Many blocks have an “Align” setting on the toolbar. This is used for multiple purposes, depending on the block, including:
- To set the block width. Choices are usually “Content width” (confusingly described as “None”), “Wide” or “Full-width” (meaning: container width).
- To set alignment within the block width (e.g. left, right or centre). This is what the Paragraph block uses the Align setting for.
- To turn on or off image stretch (e.g. normal size or stretched to fill the width)
- To turn on or off text wrap around an image
- 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. If the block’s parent container has “Inner blocks use content width” turned off, then the block cannot alter its width and may not have the Align setting. If the block uses the Align setting for other purposes, then the Align setting will be present, but won’t allow the width to be altered.
Example of potential user confusion from lack of comprehensive documentation
The ambiguity of the Align setting and it’s poor documentation, and the lack of complete descriptions of how Container width is set and inherited, lead to baffling behaviour at times.
An example is 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.
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,
This overview should also explain how to use these features in practice, with some good illustrations and worked examples!