Image block

Go to the List of Blocks

Use the Image block to easily add an image to your page.

Add an Image block

To add the Image block, click the (+) icon to open the block inserter pop-up window. Look for the Image block using the search bar and click the block icon to add it to the editor.

Alternatively, you can quickly add the Image block by typing /image and pressing Enter.

Initial options

After adding the Image block, you have a few options to choose to get started.

• Upload an image or video from your device
• Choose Media Library to select an existing image or video on your site.
• Select Insert from URL to add an image from a specific web address.

Insert from URL

After choosing Insert from URL, follow the steps below:

• Paste the image URL and press Enter to add the image to the page.
• To save a copy of the image to your site, select Upload to Media Library (up arrow) in the block toolbar.
• WordPress saves the image to your Media Library and updates the block to use the file from your site instead of the original website.

Note: This option may not work with every image or website. Some websites block images from being embedded or copied this way. Only use images you have permission to use.

Additional ways to add images

There are also additional ways to add images:

Drag/drop images

You can drag and drop images from your computer onto a blank page or inside an empty Paragraph block.

Media tab

You can select images from the Media tab in the WordPress block inserter. The Media tab also allows you to select images from the WordPress Openverse library for stock images if enabled in your theme.

1. Click the Block Inserter (+) button in the top-left corner.
2. In the inserter panel that slides out, click the Media tab.
3. Select an image from the Media Library to add to your page, or Openverse if the option is available.
4. Images can also be dragged from the Media tab to replace an existing image on the page.

Images added to your page from Openverse will automatically be uploaded to your Media Library.

Copy images from a document

You can copy and paste images into the editor from tools like Google Docs.

When you paste an image from another source, the image may still be hosted outside your site. This can cause the image to break later if the original file is moved, deleted, or no longer shared.

To save the image to your site:

1. Copy and paste the image into the editor.
2. Select the image.
3. Select the Upload to Media Library button in the block toolbar.

WordPress will save a copy of the image to your Media Library and update the Image block to use the file from your site.

Update image details

After uploading or selecting an image, customize the image details in your Media Library, such as the Title, Caption, Alt Text, and Description. This data is helpful for SEO, accessibility, and helps you search for files in your media library.

If uploaded images contain captions, they will automatically display. You can hide or show image captions in the block toolbar.

Resizing images

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

To resize an image,

• Click on the image to reveal the draggable resize handles.
• Click on the resize handles and drag the image to your desired size.

Detailed instructions on adding blocks

Block toolbar

Each block has its own block-specific controls that allow you to manipulate the block right in the editor. The Image block contains the following options:

• Transform to
• Move controls
• Apply duotone filter
• Change alignment
• Link
• Crop
• Add text over image
• Add/Remove caption
• Replace
• More options

Transform to

The Transform to tool allows you to convert the Image block into Columns, Group, Gallery, Cover, Details, File, or the Media & Text block. From this setting, you can also apply any style options your theme has enabled for the block.

Move controls

Click the the drag/drop button (six dots) to move the block to a new location on the page. A blue separator line appears to indicate where the block will be placed.

The up and down arrow icons can be used to move the block up and down on the page.

Get more information about moving a block within the editor.

Change alignment

Use the Change alignment tool to modify the alignment of the Image block. Select the tool and pick one of the following alignment options:

• None – Leaves the block the current size.
• Wide width – Increase the width of the post beyond the content size.
• Full width – Extend the block to cover the full width of the screen.
• Align left – Make the block left-aligned.
• Align center – Make the block alignment centered.
• Align right – Make the block right aligned.

Wide width and Full width only display if these width options are supported in your theme.

Wrap text around images

You can wrap text around an image by aligning the image to the left or right.

1. Add the image directly above the paragraph.
2. Select the image.
3. Resize the image to be smaller.
4. In the block toolbar, select Align left or Align right.
5. The paragraph text will wrap around the image.

For best results, use this option with smaller images. Large images can make the text hard to read, especially on mobile devices.

Duotone

The block toolbar applies a quick action for applying Duotone colors if enabled in your theme. Each theme provides different color options.

Captions

Click the Add caption button in the block toolbar to show or hide a caption for an individual image.

• Select the Add caption button in the block toolbar.
• Select the Image block and enter your caption in the space below the image.
• To hide the caption, select the Add caption button again.

Link

You can choose link options to apply to an image. Options include the following:

• Search field – Paste a URL or search for a page, post, or other content on your site to link the image.
• Link images to image file – Link image to the image file in a new browser window.
• Link images to attachment page – Link the image to its WordPress media attachment page. 
• Enlarge on click – Lets visitors open the image in a larger view, known as a lightbox, without leaving the page to see more detail.

Crop

Use the Crop button in the block toolbar to make basic edits to an image directly in the editor. After clicking on the Crop button, you can select from the following options:

• Zoom in or out on the image.
• Change the aspect ratio to crop the image to a specific shape.
• Rotate the image if it appears sideways.

After making changes, select Apply to update the image in the block.

Note: WordPress saves the edited version as a new image file, so the original image remains available in your Media Library.

Undo changes

After applying changes to an image, you can revert them using the Undo option in the action notice or the Undo button in the top-left of the block editor next to the Block Inserter button (+).

Add text over image

Use the Add text over image button to change an Image block into a Cover block. This lets you place text on top of the image.

When you select Add text over image, the Image block immediately changes into a Cover block with placeholder text. Replace the placeholder text with your own text.

Use this option when the image is decorative or when the text can remain readable over the image. For better readability, adjust the overlay color or opacity in the Cover block settings.

Replace

Use the Replace button to select a new image from the Media Library, Upload a new image, or Reset the image block back to it’s initial setup options.

More options

The More options menu (three dots) includes common block actions, such as copy, duplicate, lock, and edit as HTML.

The Image block also includes a Set as Featured Image option. Use this option to set the selected image as the featured image for the post or page.

Read about the More options menu and its settings.

Block settings

Every block has specific options in the editor sidebar in addition to the options found in the block toolbar. If you do not see the sidebar, click on the Settings button next to the Save/Publish button.

The Image block settings panel is divided into three tabs – Content, Settings, and Styles.

Content

Media

Select the image thumbnail or file name under Media to upload a new image, choose one from the Media Library, or reset the image. You can also use the Media options menu (three dots) next to Media to reset the image or alternative text.

Alternative text

Adding alternative text directly in the Media Library sets it as the default for that image. When you insert the image into a page or post using the block editor, this alt text will automatically carry over. Keep in mind that if you change the alt text within the block settings later, that edit only applies to that specific page or post.

Settings

Resolution

You can also choose the Resolution of your image with options that may include Full Size, Large, Medium and Thumbnail depending on what your theme supports and the size of the originally uploaded image.

Learn more about image size and quality

Advanced

The Image block provides the following Advanced settings options: HTML Anchor, Additional CSS Class(es), Additional CSS, Title attribute, and Styles.

The Title attribute can be used to describe the role of this image on the page, however many devices and browsers do not display this text.

Learn more about advanced settings

Styles

Style options

The Styles section appears if your theme includes custom image style options. The available styles may vary, but common options include Default and Rounded. The Rounded style adds rounded corners to the image.

Filters

You can create a filter effect on images without actually changing the original image. The Duotone filter option allows you to add this filter color to your block content from the block toolbar.

Read more about the filter options.

Dimensions

The Image block provides dimension settings options to change margin size.

For details refer to this support article: Dimension settings overview

Aspect ratio

Use Aspect ratio to change the shape of the image on the page, such as square, portrait, or landscape. Some aspect ratios may visually crop the image to fit the selected shape. This only changes how the image is displayed and does not edit the original image file.

Choosing an aspect ratio may show additional settings, including Width and Height, Scale, and the Focal point picker.

Width and height

Use Width and Height to set the display size of the image.

In most cases, leave these fields set to Auto. To resize the image, set the Width value and let the height adjust automatically. Use percentages only when you want the image to scale relative to its container.

Avoid setting a fixed height unless the image needs to fit a specific design, because it can make the image harder to control across different screen sizes.

Scale

Use Scale to control how the image fits inside the selected aspect ratio.

• Cover – Fills the entire image area. Parts of the image may be cropped so there are no empty areas.
• Contain – Shows the full image. This may leave empty space around the image if its shape does not match the selected aspect ratio.

Focal point

Use Focal point to choose which part of the image stays in view when the image is cropped. This setting is most useful when Scale is set to Cover, because Cover may crop part of the image to fill the selected shape.

Border & Shadow

The Image block provides border settings options to add border color, width, radius and shadow.

For details refer to this support article: Border & Shadow Settings overview