Block Editor – Images

previously published as “Gutenberg Blocks – Images”

These are the standard Block Editor image blocks:-

  • image
  • inline image
  • gallery
  • cover image
  • media and text


Choosing an Image block allows images to be added from your computer or from the media library (ie already uploaded to WordPress), just as in the classic WordPress editor. After uploading/choosing the image, image size and other settings can be chosen in the block settings sidebar.

An image can be inserted at any of the standard media sizes, or modified in size in a number of ways.  Changing size is easy, either by %ge or by exact pixel dimensions (just enter width and height will be calculated in proportion – the value does not appear immediately in the settings but the image size is changed appropriately. Entering height does not seem to have any effect, at present).

Image Captions can be added easily by clicking on the “Add Caption” icon in the block controls bar above the image block. This opens up the Caption area, where you can type your caption, with handy formatting options, such as bold, italic and links.

Alt Text for the image (alternative text describing the image content) can be entered in the block settings, in the sidebar. This is important for accessibility and also valuable for search engine optimisation.  Alt Text is not automatically added for an image block (unlike the classic WP editor, which does provide default “alt text” when adding an image). So it is important to enter this in the block settings when adding an image.


thumbnail image block

Medium Size

medium image block

Large Size

large image block
This image has a caption

Left- or Right-Aligned

left-aligned image block

Images can also be positioned to the left, right or centre, as in the classic editor.

left-aligned image block

But best to enclose a left- or right-aligned image within a group block, along with the content which is to sit beside it, as above. The group block allows you to contain everything within the site’s page widths. Without using an enclosing group, the image may well sit way off to the edge of the browser window, which you probably don’t want.

Inline Image

It is also possible to insert an image directly within paragraph text, like this

To add an inline image, follow these steps:-

  • add a standard text block eg paragraph and type in your content
  • position your cursor where you want the inline block to appear
  • click on the More dropdown in the top right of the block toolbar
  • choose or upload your image
  • it will be inserted at the cursor location
  • resize as desired by changing the image width
adding an inline image to a text block


The Gallery block type is initially very similar to the single Image block type, but allows several images to be uploaded or chosen rather than just one.

Gallery block options include:-

  • number of columns (from 1 to 3, which seems rather limited. It may be possible to override this with CSS styling)
  • cropped or uncropped images
  • link image to full size image, attachment page or nothing 

We can choose cropped images

Or uncropped images

The gallery is added into the page as a set of figures (in classic WP editor it is a list).  The gallery element (also a figure) has class wp-block-gallery (with additional class is-cropped, if applicable, and columns-x where x is 1, 2 or 3) and the individual figures have class wp-block image

Styling is done using flexbox settings.

Gallery image sizing

When the number of images is not a neat multiple of the number of gallery columns, thumbnails are expanded to fill the width. This is the default Block Editor styling.

Cover Image

Very simply, the Cover Image block allows you to add an image with text sitting in front of it, like this (where the word “Enlightenment” is not part of the image but has been typed directly into the block):-

cover image block


An overlay is automatically added to a cover image block, to provide a level of opacity (shading) on the image, so that the text is clearer to read. The opacity setting allows you to adjust the opacity to your satisfaction.

Here is this image without any overlay.

cover image without overlay

As the name suggests, the Cover Image block is most likely to be used as a hero header section for a page or post. For best effect, some of its settings require explicit support within your WordPress theme.  For a more detailed explanation, read this post on Block Editor – Cover Image.

Additional information about cover images, and how they can be used, can be found here

Media and Text Block

Include a Heading

The Media and Text block adds a section which allows you to insert an image on one side and add text or other blocks on the other.

media and text block

You can choose to have the image on the left or the right, and also whether the content should be vertically centred or sit at the top (or bottom).

The entire block has a class of wp-block-media-text, with interior blocks, wp-block-media-text__media and wp-block-media-text__content.

media and text block on mobile

On mobile, the Media and Text block rearranges to show the image at the top and the content beneath (regardless of whether or not the image was positioned on the left or the right).