Back to Support Content and Media Blocks Image Block

Image Block

Use the Image block to insert an image onto your page or post. This guide describes how to insert an image and use all the available settings to control how the image appears.

Video Tutorial

Video Transcript

In WordPress, you can insert images into your pages and posts using the Image Block.

To add an image block, click the Block Insert button and then search for the Image Block. Or, type a forward slash on a new line followed by the word Image. Then, press Enter to add the Image Block.

Next, you can upload an image from your computer to your site, or select an image from your media library, your Google Photos account, or the Pexels Free Photo Library. You can also insert an image from a URL if the image is hosted somewhere else. But you can also simply drag an image from your desktop directly into the image block to upload it to your site and embed it in one step.

In the toolbar, there are options to drag the image into a different location on the page or move the image up or down the page using the arrow buttons.

If you’d like to get a little creative, you can also apply a duotone filter to create a two-tone color effect. You can select one of the preset color combinations or choose the colors you’d like to use for the shadows and the highlights. To remove the effect, click the Clear button.

You can change the width of the image and align the image on the left, center, or right.

The link settings allow you to choose what happens when a visitor clicks on this image. You can link to a specific web address by pasting a URL into this field. Click the Apply button to create the link. Or you can link the image to an existing page or post on your own site. Start typing the title of the page or post and then select it from the results to create the link. If you prefer, you can link the image to its own dedicated attachment page or the full-sized version of the image file.

Click the Crop icon, and several additional editing tools will appear. You can zoom in on your image up to 300%, then click and drag to control which part of the image is visible.

You can also change the aspect ratio from the original width and height to square, or Landscape Mode, or Portrait Mode. And again, you can click and drag the image to change the portion that’s visible.

You can rotate the image by 90 degrees, 180, 270, or 360. When you’re happy with your changes, click the Apply button to commit your changes to the image or click the Cancel button to exit without making any changes.

If you like, you can add text over the image. Clicking this button will change the image block into a cover block, with the image now being used as the background. Then, you can add any text you like or another block.

To convert the cover block back into an image block, first, select the parent cover block. Then, click the Transform button and select the image block. Of course, you can always replace this image with another one any time you like.

To resize an image, click one of the handles and then drag the image until it’s the size you want.

With the image resized, you may choose to align the image to the left, or right of your page, which will allow your text and other content to wrap around the image.

To add a caption to your image, click in the caption space below the image and add any text you like. Then, you can format the text or add a link.

There are a few additional settings for the image block.

First, you can choose a style for the image. Choose between a rounded frame or the default style.

It’s always a good idea to add an alternative text description, which not only gives search engines an idea of what this image is but also helps your visually impaired visitors to know what the image represents.

By default, WordPress displays a thumbnail version of the image when it’s added to your page, which helps the page to load faster. But you can select a larger version with higher resolution if you like.

And you can adjust the dimensions of the image by entering a value in the Width or Height fields or select a percentage from the Preset options below.

And finally, you can round the corners of an image by entering a value for the border-radius.

With all these options, the image block provides a lot of flexibility for adding images to your pages and posts.

For more help adding images to your website, please visit

Add the Image Block

To add the Image block, click the + Block Inserter icon and search for “image”. Click it to add the block to the post or page.

Screen recording on how to add an image block.
Inserting an Image block using the + Block Inserter.


Using your keyboard, you can also type /image on a new line and press Enter or click on the Image option in the menu to quickly add a new Image block.

How to add an image block.
Insert an Image block by typing /image on a new line.

For more information, visit our detailed instructions on adding blocks.

Insert an Image

Once you add the Image block as described in the previous section, you will be presented with three methods to select your image:

An empty image block shows the Upload, Select image, and Insert from URL option.
Options to add an image

Resize the Image

After you have added an image to the Image block, you can change the size. Click the image to reveal the resize handles that look like dots around the image. Then, click on a resize handle and drag the image to your desired size:

Resize an image by dragging its handles.

To fine-tune the size and aspect ratio of an image, jump to this section.

Block Toolbar

When you click on the block, a toolbar of options will appear:

Image block toolbar
Image block toolbar

The icons on the Image block toolbar, starting from the left, are:

Align Images

Use the alignment options to make the image appear on the left, the right, or in the center. Additionally, you may see options for wide width and full width, if those are supported by your theme.

Further reading: Align Images With Text


To add a caption, click on the Caption icon in the block’s toolbar to enable a caption for that image. Then, type the caption in the Add caption box below the image:

An arrow points to the caption icon in the toolbar, and a second arrow points to the spot below the image to type a caption.
Enable (1) and type (2) a caption for an image.

If you want to modify a caption that has already been added to an Image block, you can do that by clicking on the caption and either replacing or adding text.

If you have written a caption for an image in the Media library and then added the Image block, the Image block will show the caption you wrote. However, if you add a caption to the image in the Media library after adding the Image block, that caption will not appear in the Image block. In that case, you can either type the caption manually on the Image block or remove and re-add the block so that it will use the caption from the Media library.

To add a link to an image, click the link icon in the toolbar — it looks like the link of a chain:

The link icon.

You will then be presented with several options, explained below:

The link button has been clicked, and the options for adding a link are presented.
Your image can link to a custom URL, Attachment Page, or Media File.

A text box appears where you can:

Press the arrow icon, or the return or enter key on your keyboard, to save the link. If you click the downward arrow next to that box, you can choose whether or not to have the link open in a new tab.

You may also choose to link the image to:

To remove an existing image link, click on the link icon on the toolbar and then on the “Remove link” X icon:

Screenshot showing how to remove an existing image link.

Crop and Other Image Editing Tools

Click on the Crop icon in the toolbar, and a selection of editing tools will appear:

Image block editing tools showing the zoom ,aspect ratio, rotate, apply, and cancel options.

From left to right, these are:

Edits you make to your image will create a new copy of the image in the Media Library. This ensures that if the image is used elsewhere on your site, it won’t be affected. It also means you still have the original image if you need it.

Replace Image

You can replace the image on the Image block via the ReplaceSelect Image option on the block toolbar:

Replacing an image.

Block Settings

When you select a block, you will find additional block settings in the right sidebar. If you do not see the sidebar, you may need to click the Settings icon in the top-right corner to bring up the settings. This icon looks like a square with two uneven columns:

The settings icon in the Editor with a tooltip "Settings" below it.
Click the Settings icon to open the block settings

The Image block settings contain a Settings menu and a Styles menu. Select the corresponding button under the Image block information to open those options.

Block Settings Menu
Block Settings Menu

Alternative Text

Use the Alternative Text field to describe the purpose of the image. This text is used by search engines and screen readers.

The image settings section of the Image Block settings sidebar displaying alternative text aspect ratio and image dimension options.

Aspect Ratio

The aspect ratio is the relative size of the width and height of an image. For example, an aspect ratio of 1:2 would mean the image’s width is half the size of the image’s height.

Changing the aspect ratio to Standard - 4:3, then Classic Portrait - 2:3, showing how the image changes.

You can choose from the following common image dimensions:

When an aspect ratio other than the original is selected, the Scale option will be available. Scale refers to how your image fits within your selected aspect ratio with the following options:

Width and Height

Set a custom width and height by typing pixel values in the Width and Height boxes. If you resize the image using the drag handles, these boxes will automatically update with the image’s new width and height. Erase the numbers from these boxes to return the image to the automatic size.

Image size controls in the block settings
Image width and height controls in the block settings


In the Resolution box, you can select the size of the image, among Thumbnail, Medium, Large and Full Size.

Screenshot of Image block's Resolution control in the block settings.
Image Resolution control in the block settings.

Expand on Click

By enabling the Expand on Click toggle, you can allow your visitors to click on an image to view it in an enlarged format, known as a lightbox.

When this toggle is enabled and visitors hover over images, their mouse pointer will change into a magnifying glass. Clicking on the image will open it on the lightbox.

Your visitors can revert the image to its normal size by clicking anywhere on the enlarged image or its surroundings, or by pressing the Escape key.

You can see it in action by clicking on the screenshot on the right.

Any existing image link should be removed for the image to open on a lightbox.


For more, visit our detailed instructions on Advanced settings.


In the block settings sidebar, click on the Styles icon to access the design settings for the block. The Styles icon is in the shape of a circle with half of the circle filled in:

An arrow points to the Styles icon that you can click to open up the block styles section.

Choose the style of the image, which can be set to:

  • Default: the image appears as you inserted it.
  • Rounded: the image appears as a circle (if your image was originally square) or a capsule/oblong shape (if your image was originally a rectangle).

Add a two-tone color effect using the duotone filter setting.

The styles section of the Image Block Settings sidebar, including filters, borders, and radius.

Border and Radius

For more, visit our detailed instructions on Border settings.

Was this guide helpful for you?

Not quite what you're looking for? Get Help!

Copied to clipboard!