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 on 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, visit our detailed instructions on adding blocks.

Once you add the block, you will be presented with three methods to select your image:

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

The link settings allow you to hyperlink your images. You may choose whether clicking on the image opens an attachment page, the original media file, or a custom URL of your choice.

To link to a specific URL, enter the URL you want the image to link to in the text box that appears. 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.

Alternatively, if you wish to link an image to a page or post on your site, start typing the title of the page or post. You can then select it from the results and link the image to that page or post.

Adding a link to an image
Your image can link to a custom URL, Attachment Page, or Media File.
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:

Here is a demonstration of how the zoom feature works:

Use the Zoom tool to crop the image to the size and content you wish to see.

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.

Duotone Filter

The duotone filter option allows you to set image colors from the block toolbar. Think black and white photos, but in any color combo of your choosing. To get started, select the Duotone Filter button in the toolbar, then choose from the examples shown, or set your own colors.

A gif of an image being clicked in the Editor, then applying several different Duotone Filters to see how it looks.

To set your own colors, select the dots within the color bars:

A screenshot highlighting where to click on the Duotone filter setting to set a custom color, on the color bar.

Resize Image

Once you have added the image to the editor, you can resize and align the images to better fit the surrounding content.

Resize an image by dragging its handles.

To resize an image, click it to reveal the resize handles that look like dots around it. Then, click on a resize handle and drag the image to your desired size.

Alternatively, you can adjust the width and height dimensions in the block settings on the right-hand side. There are also convenient options for setting the image to 100, 75, 50, and 25% of its original size.

Image size controls in the block settings
Image size controls in the block settings

Replace Image

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

Replace an image.


To add a caption, enable the Caption on the block’s toolbar, and type the caption in the Add caption box below the image in the editor:

A screenshot on how to enable and add a caption on an image block.
Enable, and add a caption for an image.

If you have written a caption for an image in the Media library and then add 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.

Block Settings

You will find additional block settings in the right sidebar when you click on the block. 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 black background and the tooltip "Settings" below it.
Click the Settings icon to open the block settings
Image block settings
Image block settings

The Image block settings contain the following options:


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

Note that the options for Styles covered above may not all be available, depending on the theme that you’re using for your site.

Image Settings
Border and Radius

The Border allows you to add a colored line along the edges of your images.

The Radius allows you to give your image borders a rounded appearance. Setting the radius to 0 means the image has sharp edges.

You can adjust the Border and Radius settings by clicking on each of the corresponding numbered sections as explained below:

Border and Radius settings on the Image block.
  1. Click on the circular icon to select a color for your borders.
  2. Type a number into the box area to select the thickness of your borders or the roundness of your border radius in the lower box.
  3. Click the PX icon to change the unit of measurement for the border thickness or radius. You can choose between PX % EM REM VW and VH.
  4. Click on the colored dot and slide to increase or decrease the selected value for the thickness of your borders or the roundness of your border radius.
  5. Click on the three dots (ellipses) icon to reset the previously selected settings for your border or radius.
  6. Click on the colored link icon to unlink the values for your border or radius. This means that you can select different values for each side of the border or radius. Below is an example of an image with unlinked values used to create a multi-colored, blob-shaped border.
Unlinked Border and Radius values adjusted to create a multi-colored, blob-shaped border around an Image block.


The settings for Border and Radius may not appear on your site if you’re using a classic theme. You may want to explore some of our new Site Editor themes for the ability to customize your image borders, and so much more!


The advanced settings allow you to create an HTML anchor for the current block which can be used to create a hyperlink to it, add additional CSS classes and also add/remove space from top/bottom of the block.

Learn more about HTML anchors here and learn more about adding additional CSS classes to blocks here.

Was this guide helpful for you?

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

Copied to clipboard!