The Ultimate Guide to Gutenberg Image Alignments in WordPress Themes

I’m writing a number of articles outlining the tricks the trade I’m learning while developing Gutenberg-ready WordPress themes. Up next is this guide on supporting Gutenberg’s new alignment features. Woot!

In the coming months, the WordPress editor will receive a major overhaul — quite possibly the biggest evolution that WordPress will experience within the next decade. And with the introduction of the new editor (Gutenberg), gone will be the days of messy WYSINRWYG (what-you-see-is-not-really-what-you-get) visual editing. Instead, we’ll have a refreshing interface that empowers users to build beautiful content.

After working with the new editor over the last few months, I’m excited for the future of WordPress, and particularly WordPress themes.

Supporting the new wide alignment feature

With the release of WordPress 5.0, Gutenberg will introduce two new content alignment options: wide and full width. While WordPress themes are not required to support the new alignment options, it’s not much work to bake them in, thus empowering users that much more.

To start, simply use the add_theme_support( 'align-wide' ) function to the theme’s functions.php file, attached to the after_setup_theme hook, which is fired after the theme is loaded:

Note that theme support for wide images was changed from being within the Gutenberg theme support array, with a wide-images bool, to the above. Refer to issue #4113 and this pull request on the Gutenberg GitHub repository to explore why those changes were made.

If you’ve updated your WordPress theme(s) prior to the change above, you’ll need to update them once again. ?

Blocks that support new content alignments

Listed below are the Gutenberg blocks that currently support the new wide and fullwidth content alignment options within Gutenberg. When you’re adding support for the new alignment options, you’ll want to run each of these blocks through its paces to ensure it displays properly.

  • Pullquote Block
  • Gallery Block
  • Image Block
  • Cover Image Block
  • Video Block
  • Table Block
  • Columns Block
  • Text Columns Block
  • Categories Block (fullwidth only)
  • Embed Block

Classes for the new alignment options

Now that you’ve declared support for the wide and full width content alignment options and have identified what blocks to test, your users will be able to position capable content as such. So let’s add some styling.

First off, there are two new classes to add to your stylesheets: .alignwide and .alignfull. The .alignwide class is used to display content that is a bit wider than the rest of the content, while the .alignfull class displays content that is 100% full width.

There are a number of methods to style the new alignment options, which are entirely dependent on your WordPress theme’s content structure. Let’s take a look at the two main variations.

Styling alignments within max-width containers

If your WordPress theme has a container with a max-width assigned to it, you’ll need to calculate the margin for which the content needs to be pulled to the viewport edges, like so:

The above works wonderfully for the full width elements, but for wide aligned content, we need to set a max-width and pull the element outside the bounds of the post’s container:

It’s relatively easy to add support for the new alignments within Gutenberg for WordPress themes that utilize a content container with a set width. But what about themes that do not assign a specific width to their content container?

Styling alignments in a container without a max-width

If your WordPress theme relies on a content container which has no max-width, it is not feasible to apply a max-width to every block that could be added within Gutenberg. It’s simply not scalable; especially as developers build companion block plugins, like I’m doing for Writy.

Instead, apply a max-width to every child element within the content container that isn’t a wide or full width image, like so:

Now we’re talking. This technique is scalable. Every child element of content container, except for .alignwide and .alignfull elements, will display centered, at 740px wide, with a 20px padding on each side to prevent the content from sitting against the viewport.

Next, establish the max-width for any wide aligned content. Again, this should be a bit larger than your content’s main container, to give it a proper wide aligned treatment.

Using either method, the result is the same. Users will now be able to set images, and other content, to display wide or completely full width.

Floating right and left aligned images in a container without a max-width

If you’re using the second method I mentioned, where immediate child elements of a container are targeted and styled, then you are probably wondering how to effectively style the .alignleft and .alignright alignments within this context.

We need the floated content to sit properly within the confines of the established max-width — as all other blocks do.

So instead of only assigning a float to the .alignleft and .alignright classes respectively, we can leverage the new markup provided by Gutenberg to position these images properly. Simply float the image within the figure, which has the assigned alignment class, like so:

Considerations for the Cover Image Block in a container without a max-width

The Gutenberg Cover Image Block is unique in that the alignment classes assigned are generated on the main <section> tag. That means there’s no additional markup within the <section> tag that can be floated for left and right alignments.

You’ll need to ensure that the floats exist for the .wp-block-cover-image right and left alignment options.


Supporting Gutenberg’s new full and wide alignment feature is the first step in preparing WordPress themes for the new editor.

While uncertainty surrounds exactly how WordPress themes and Gutenberg will interface, I’m confident that we’ll start to see a new generation of themes that wholeheartedly embrace Gutenberg — not just support it.

I am sparking that generation, starting with Writy, an upcoming WordPress theme built with a “Gutenberg-first” mentality. Click here to subscribe to updates — we’ll also probably hit you up soon about an upcoming private beta.

WordPress themes have a lot of growing up to do in a post-Gutenberg era of WordPress, but the field is ripe for opportunity. Are you jumping onboard?