Title: Image block
Author: kriskorn
Published: March 7, 2019
Last modified: April 16, 2026

---

# Image block

## In this article

 * [Add an Image block](https://wordpress.org/documentation/article/image-block/?output_format=md#add-an-image-block)
 * [Block toolbar](https://wordpress.org/documentation/article/image-block/?output_format=md#block-toolbar)
    - [Adding an image](https://wordpress.org/documentation/article/image-block/?output_format=md#adding-an-image)
    - [Resizing images](https://wordpress.org/documentation/article/image-block/?output_format=md#resizing-images)
    - [Aligning images](https://wordpress.org/documentation/article/image-block/?output_format=md#aligning-images)
    - [Wide and full width images](https://wordpress.org/documentation/article/image-block/?output_format=md#wide-and-full-width-images)
    - [Captions](https://wordpress.org/documentation/article/image-block/?output_format=md#captions)
    - [Link settings](https://wordpress.org/documentation/article/image-block/?output_format=md#link-settings)
    - [Image editing](https://wordpress.org/documentation/article/image-block/?output_format=md#image-editing)
    - [Adding text overlay](https://wordpress.org/documentation/article/image-block/?output_format=md#adding-text-overlay)
    - [More options](https://wordpress.org/documentation/article/image-block/?output_format=md#more-settings)
 * [Block settings](https://wordpress.org/documentation/article/image-block/?output_format=md#block-settings)
    - [Image settings](https://wordpress.org/documentation/article/image-block/?output_format=md#image-settings)
    - [Style settings](https://wordpress.org/documentation/article/image-block/?output_format=md#styles)
    - [Styles](https://wordpress.org/documentation/article/image-block/?output_format=md#styles-2)
    - [Filter options](https://wordpress.org/documentation/article/image-block/?output_format=md#filter-options)
    - [Dimensions](https://wordpress.org/documentation/article/image-block/?output_format=md#dimensions)
    - [Border and shadow](https://wordpress.org/documentation/article/image-block/?output_format=md#border-and-shadow)
    - [Advanced](https://wordpress.org/documentation/article/image-block/?output_format=md#advanced)
 * [Changelog](https://wordpress.org/documentation/article/image-block/?output_format=md#changelog)

[ Back to top](https://wordpress.org/documentation/article/image-block/?output_format=md#wp--skip-link--target)

[Go to the List of Blocks](https://wordpress.org/support/article/blocks/)

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

## 󠀁[Add an Image block](https://wordpress.org/documentation/article/image-block/?output_format=md#add-an-image-block)󠁿

To add the Image block to a page, click the** Add block** button to open the block
inserter pop-up window and choose the Image block.

You can also use the keyboard shortcut `/image` to quickly insert an Image block.

![Add an image block in the editor by typing /image](https://wordpress.org/documentation/
files/2019/03/Screenshot-2026-03-02-at-4.10.12-PM-1.png)

[Detailed instructions on adding blocks](https://wordpress.org/documentation/article/adding-a-new-block/)

## 󠀁[Block toolbar](https://wordpress.org/documentation/article/image-block/?output_format=md#block-toolbar)󠁿

![Block toolbar over an image taken from on the moon during the Apollo mission](
https://wordpress.org/documentation/files/2019/03/Screenshot-2026-03-02-at-4.15.23-
PM-1024x505.png)

Each block has its own block-specific controls that allow you to manipulate the 
block right in the editor. 

 * Transform to
 * Block moving tools
 * Align
 * Apply duotone filter
 * Link
 * Crop
 * Add text over image
 * Add/Remove caption
 * Replace
 * More options

### 󠀁[Adding an image](https://wordpress.org/documentation/article/image-block/?output_format=md#adding-an-image)󠁿

The media options panel will load with three options, Upload, Media Library, and
Insert from URL.

![Image add options in editor](https://wordpress.org/documentation/files/2019/03/
Screenshot-2026-03-02-at-4.18.53-PM-1024x360.png)

Upload and Media Library will let you add or choose media from your library and 
embed it in your page.

Simply add the image from the Upload Files tab, then select it in the Media Library
tab. Customizing the image attachment details, such as the Title, Caption, Alt Text,
and Description, in the Media Library window can also be helpful for SEO and future
navigation of your media library.

![Upload or select an image from your Media Library, add image information, then
press Select.](https://wordpress.org/documentation/files/2024/01/292768016-cd56a1c7-
5958-47fa-ab52-392ca8fbff32-1024x683.png)

Upload or select an image from your Media Library, add image information, then press
Select.

It is also possible to drop image into empty paragraph.

As well as choosing an image from [Openverse](https://openverse.org/en-gb), which
will be uploaded to your site’s Media.

Openverse images can also be dragged from inserter to existing image block.

#### 󠀁[Importing external images](https://wordpress.org/documentation/article/image-block/?output_format=md#importing-external-images)󠁿

If you selected the “Insert from URL option” to add your image, you will see a button
with an upward facing arrow. If you click on it, the image will be imported into
your site’s local Media Library and the URL on the image block will be automatically
updated to point at the new file.

Setting the image via an external URL and then importing it to the local Media Library.

If the imported image has a caption, it will be added automatically as well.

Please note that the “Upload External Image” feature might not work on all websites,
as some of them restrict how their images are handled.

### 󠀁[Resizing images](https://wordpress.org/documentation/article/image-block/?output_format=md#resizing-images)󠁿

Once the image is added 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 on the image to reveal the draggable resize handles.
 * Click on the resize handles and drag the image to your desired size.

Alternatively, on the right-hand side in the Block Settings, the image size can 
be fine-tuned by adjusting width and height dimensions. There are also some convenient
options in the block settings for setting the image to 100, 75, 50, and 25% of its
original size.

### 󠀁[Aligning images](https://wordpress.org/documentation/article/image-block/?output_format=md#aligning-images)󠁿

Align an image within a paragraph block.

If you wish to align an image within a paragraph you will first need to insert the
image _just above the target paragraph block._

![Alignment buttons with Align left highlighted](https://wordpress.org/documentation/
files/2024/01/292768021-bc7359b8-c035-4fa5-907f-c08e70f264f5.png)

Alignment buttons with Align left highlighted

From there, click on the image and select left or right alignment, this will merge
the image into the paragraph block.

Finally, resize the image to your desired width and height.

### 󠀁[Wide and full width images](https://wordpress.org/documentation/article/image-block/?output_format=md#wide-and-full-width-images)󠁿

As support for the new editor is added to our themes, you will begin seeing icons
for Wide and Full Width images. These two image sizes will allow you to expand the
image beyond the theme’s usual content width.

A ‘Wide’ image in the editor.

### 󠀁[Captions](https://wordpress.org/documentation/article/image-block/?output_format=md#captions)󠁿

![Block toolbar with caption button highlighted](https://wordpress.org/documentation/
files/2019/03/caption-Screenshot-2026-03-02-at-4.24.23-PM-1.png)

If you wish to add a caption to a singular instance of an image, click on the Add
caption button on the Block toolbar. Then enter your caption text into the space
below the image. You can remove the caption by toggling the caption button off.

![Example of an image of an astronaut on the moon with a caption below it that reads"
Apollo 15 Commander Dave Scott and the LRV" by Apollo Image Gallery.](https://wordpress.
org/documentation/files/2019/03/Screenshot-2026-03-02-at-4.24.10-PM-1024x869.png)

### 󠀁[Link settings](https://wordpress.org/documentation/article/image-block/?output_format=md#link-settings)󠁿

The link settings allow you to hyperlink your images. You can enter a custom URL,
link to the image file, link to an attachment page or choose to enlarge the image
when the site visitor clicks on it.

![Block toolbar link section expanded to show Link to image file, Link to attachment
page and Enlarge on Click](https://wordpress.org/documentation/files/2019/03/Screenshot-
2026-03-02-at-4.57.01-PM-1024x433.jpg)

#### 󠀁[Enlarge on click](https://wordpress.org/documentation/article/image-block/?output_format=md#enlarge-on-click)󠁿

The Enlarge on Click option creates a link in the image that opens it to a bigger
size, as a dialog on the same page, when clicked. This is called the lightbox effect
and it’s useful when you want the viewer to have the chance to see a certain image
with more details.

### 󠀁[Image editing](https://wordpress.org/documentation/article/image-block/?output_format=md#image-editing)󠁿

You can make quick crops without leaving the editor. Just hit the Crop button in
the toolbar.

An expanded toolbar will appear. This will allow you to zoom an image.

![Image toolbar showcasing the zoom option](https://wordpress.org/documentation/
files/2024/01/292769877-cb010416-ecd1-4a43-8a03-85b33bdb297e.png)

Image toolbar showcasing the zoom option

There are also options to set the aspect ratio, such as to crop the image into a
square.

![Image showing the cropping tools for an Image block.](https://wordpress.org/documentation/
files/2024/01/292769878-35c519aa-d9e9-4600-a704-9e95151fa8d2.png)

Image showing the cropping tools for an Image block.

You can also rotate the image if it comes in sideways.

After you make any changes, click Apply.

#### 󠀁[Undo changes](https://wordpress.org/documentation/article/image-block/?output_format=md#undo-changes)󠁿

After applying changes to an image, you can revert them using the Undo option in
the action notice.

![Revert image edit using Undo option](https://wordpress.org/documentation/files/
2019/03/undo-image-changes-1024x576.png)

Revert image edit using Undo option

### 󠀁[Adding text overlay](https://wordpress.org/documentation/article/image-block/?output_format=md#adding-text-overlay)󠁿

A new feature allows you to convert image block to cover block so that you can add
overlay text on the image.

![Image showing the option to add text over the image](https://wordpress.org/documentation/
files/2023/12/8.png)

Image showing the option to add text over the image

Upon clicking the _Add text over image_ button the block transforms immediately 
to a cover block with its placeholder paragraph.

![Add text over image placeholder ](https://wordpress.org/documentation/files/2024/
01/292768025-50ce9264-22a7-487e-b46a-e9e955b532ec.png)

Add text over image placeholder

Sometimes you use a tool like Google Docs to write or collaborate on posts. When
you’re ready to put the content on your site, you may copy and paste them into the
editor.

One problem is that those images are likely hosted somewhere else like Google and
could easily become broken if a change is made.

So, If you copy and paste an image from a resource like Google Docs, a button will
appear on the toolbar to upload it to the media library. Click that, and it will
stay in the post, but also upload to your media library.

### 󠀁[More options](https://wordpress.org/documentation/article/image-block/?output_format=md#more-settings)󠁿

These controls give you the option to copy, duplicate, and edit your block as HTML.

[[[Read about these and other settings.](https://wordpress.org/documentation/article/more-options/)

In addition to existing options, the More options now includes a **Set as Featured
Image** option for Image block.

This allows you to directly set the selected image block as the featured image for
the post or page, streamlining the workflow without needing to open the Post settings
sidebar.

![Set as Featured Image option in More options](https://wordpress.org/documentation/
files/2019/03/set-as-featured.png)

Set as Featured Image option in More options

## 󠀁[Block settings](https://wordpress.org/documentation/article/image-block/?output_format=md#block-settings)󠁿

![](https://wordpress.org/documentation/files/2019/03/Screenshot-2026-03-02-at-5.12.06-
PM-1.png)

The block settings panel contains customization options specific to the block. To
open it, select the block and click the Settings button next to the Publish or Save
button.

### 󠀁[Image settings](https://wordpress.org/documentation/article/image-block/?output_format=md#image-settings)󠁿

![Block Settings toolbar for Image block](https://wordpress.org/documentation/files/
2019/03/settings-Screenshot-2026-03-02-at-5.11.25-PM-409x1024.png)

The image settings offer a text field to add an **Alternative Text** description,
which is important for accessibility and SEO.

You can choose the **Image size** between thumbnail, medium, large and full size.
You can also change the **Image dimensions** – width and height dimensions of an
image in 25% increments, or in exact pixel dimensions. You can also choose the **
Resolution** of your image with options that may include Full Size, Large, Medium
and Thumbnail depending on your theme and the size of the originally uploaded image.

### 󠀁[Style settings](https://wordpress.org/documentation/article/image-block/?output_format=md#styles)󠁿

![Block styles toolbar for image block](https://wordpress.org/documentation/files/
2019/03/Screenshot-2026-03-02-at-5.11.42-PM-330x1024.png)

### 󠀁[Styles](https://wordpress.org/documentation/article/image-block/?output_format=md#styles-2)󠁿

Depending on your theme, you may have several styles for your image for example 
default or rounded.

### 󠀁[Filter options](https://wordpress.org/documentation/article/image-block/?output_format=md#filter-options)󠁿

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](https://wordpress.org/documentation/article/filters-settings-overview/).

### 󠀁[Dimensions](https://wordpress.org/documentation/article/image-block/?output_format=md#dimensions)󠁿

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

For details refer to this support article: [Dimension settings overview](https://wordpress.org/documentation/article/dimension-controls-overview/)

### 󠀁[Border and shadow](https://wordpress.org/documentation/article/image-block/?output_format=md#border-and-shadow)󠁿

The Image** **block provides border settings options to add border color, width,
and radius. If there are custom border settings, custom border will be visible on
image placeholder.

For details refer to this support article: [Border settings overview](https://wordpress.org/documentation/article/border-settings-overview/)

### 󠀁[Advanced](https://wordpress.org/documentation/article/image-block/?output_format=md#advanced)󠁿

![Advanced options](https://wordpress.org/documentation/files/2019/03/Screenshot-
2026-03-02-at-4.30.58-PM-1.png)

**HTML anchor** allows you to [make a unique web address](https://wordpress.org/documentation/article/page-jumps/)
for a particular Image block. Then, you’ll be able to link directly to an Image 
block of your page.

The **Additional CSS class(es)** lets you add CSS class(es) to your block, allowing
you to write custom CSS and style the block as you see fit.

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

## 󠀁[Changelog](https://wordpress.org/documentation/article/image-block/?output_format=md#changelog)󠁿

 * Updated 2026-03-02 (props to @hu55nain @madtownlems @CalolanC @Anuj-Rathore24
   @awetz583)
    - Updated block toolbar screenshots
    - Updated block settings screenshots
    - Added caption button screenshots and information
    - Updated Advanced settings screenshot and info
    - Added information for resolution under settings
    - Added border and shadow info
 * Updated 2025-11-10 (props to @nikunj8866)
    - Add the Undo option.
    - Add “Set as Featured Image” option.
 * Update 2024-01-25 @milana_cap
    - Updates for 6.2 completed
    - Allow dropping an image on an empty paragraph block to create an image block
    - Updates for 6.3 completed
    - Display custom borders on image placeholder
    - Upload Openverse images when inserted
    - Allow dragging-and-dropping images from the inserter to image blocks
    - Updates for 6.4 completed
 * Update 2024-01-16
    - Updates for 6.1 completed
    - Re-upload missing images
 * Update 2023-12-25
    - Update screenshots and videos for 6.4
 * Update 2022-12-12
    - Added Border settings
 * Updates 2022-11-28
    - Added missing image caption
    - Replaced content on more options
 * Updated 2022-03-15
    - Added notes about converting cover block from toolbar.
 * Updated 2022-01-25
    - Updated a few screenshots to align with expanded toolbar.
    - Added notes about using duotone.
 * Updated 2021-01-04
    - Updated all screenshots to WordPress 5.6
 *  - Added section on image title attribute (Gutenberg 6.9/WP 5.4)
    - Added section about easy upload for external images (Gutenberg 8.5/WP 5.5)
    - Added section about block editor image editing (Gutenberg 8.4/WP 5.5)
    - Added details on HTML Anchor and Image Styles to Advanced
 *  - Removed pencil (edit) icon and added more option menu
    - Removed some out-of-date content
    - Re-ordered to match the current block toolbar layout
 * Updated 2020-06-18
    - Added ‘Link back to blocks’ to the top of the page
    - Added the ‘Changelog’
 * Created 2019-03-07

## Was this article helpful? How could it be improved? 󠀁[Cancel reply](https://wordpress.org/documentation/article/image-block/?output_format=md#respond)󠁿

[Log in to submit feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fwordpress.org%2Fdocumentation%2Farticle%2Fimage-block%2F&locale=en_US).
If you need support with something that wasn't covered by this article, please post
your question in the [support forums](https://wordpress.org/support/forums/).

First published

March 7, 2019

Last updated

April 16, 2026