Block Editor – Cover Image

previously published as “Gutenberg Blocks – Cover Image”

Simple Example of Cover Image Block

Very simply, the Cover Image block allows you to include an image with text sitting in front of it, like the image below (where the words “Simple Cover Image Block” are not part of the image but text typed directly into the block in the editor):-

simple cover image block

Simple Cover Image Block

The Opacity setting on the image overlay allows you to make the image darker (or lighter) so that the text is clearer to read.

The block is a <div> tag with class wp-block-cover and includes:-

  • the <img> tag, class wp-block-cover__image-background, which is styled to cover the entire cover block, with style object-fit: cover
  • a span which manages the overlay, class wp-block-cover__background
  • and an interior <div>, class wp-block-cover__inner-container, which contains all of the text content.

The interior content defaults to a paragraph with large font size and colour white, but you can add any blocks into the content, and change their settings – colour, size and so on – as for normal text blocks.


Settings for the cover image block include:-

  • Overlay opacity – default is 50%, black colour
  • Fixed background
  • Repeating background
  • Focal point of image – default is centre
  • Minimum Height – this is 430px by default, but can be set larger or smaller


By default, the cover image overlay is black, and set to 50% opacity. The overlay span has class has-background-dim, indicating that some opacity is in play.

cover image with default overlay colour and opacity

Default overlay colour and opacity

However, the background colour and opacity level can easily be changed in the settings. Additional classes, has-secondary-background-color and has-background-dim-30, for example, are added to the overlay span, based on the selected settings.

cover image with different opacity colour chosen and opacity reduced

Overlay colour chosen and
opacity reduced

Another option is to choose only a background colour (no image) for the Cover Block. In this case, the opacity is automatically set to 100%.

Cover Image with Background Colour Only
and Minimum Height of 200px

Fixed Background Effect

The Fixed Background setting allows you to keep the image fixed on the page, while the visitor scrolls down, giving an interesting visual effect, as below:-

Cover Image with Fixed Background

The additional class has-parallax is added to the wp-cover-block to indicate this setting.

This is not exactly a true parallax effect (in which the image also moves up the page, just more slowly than the text) but it does offer an interesting variation for this type of block.

As you can see, the image is used at a larger magnification, and less of it is visible at a time, in order to achieve this effect. So large images, with the “interest” in the central portion, are best for this type of effect.

Focal Point and Height

By default, the focal point of a cover image is the centre (vertical and horizontal) of the image. Different devices or different browser widths may show different amounts of the image, depending on the minimum height of the cover image block.

Specifying a focal point will cause this portion of the image to remain visible at different browser widths, as much as is possible.

cover image with focal point selected

Focal Point of child’s face selected

By default the height for the cover image is 430px, and not the full height of the image, although the block may be taller if a large amount of text is included. When choosing an image for this kind of block, it is worth bearing in mind that the image may be truncated top and bottom, with the central portion most likely to be visible. Minimum height can be increased or decreased in the settings.

Hero Header Section

As the name suggests, the Cover Image block can be used as a hero header section for a page or post.  The post’s Featured Image can be chosen as the background image, and so the block can be updated dynamically.

Some of the settings require explicit support within your WordPress theme. For example, the full width setting must be explicitly supported by the theme in order to display across the full width of the web page.

selecting full width in the block editor
Choosing the full width setting for a block

More Information

For further reading about cover images, see here

For our introduction to the block editor, see Beginning with the Block Editor and also Page Layout with the Block Editor.