Image Block

The Image block lets you add and display images within your content. It’s one of the most commonly used blocks — helping you support storytelling, improve visual hierarchy, and make content more engaging.

Why use the Image block

Use the Image block when you want to:

  • Add visual context to your content
  • Break up long sections of text
  • Highlight key information or moments
  • Support storytelling with photography, graphics, or illustrations
  • Improve scannability and engagement

Images work best when they support the content — not distract from it.

How to use the block

Start by adding the Image block to the page. Learn how to add blocks.

Once the block is added, editors typically:

  • Add an image by uploading, selecting from the Media Library, inserting from a URL, or dragging and dropping
  • Add alt text to describe the image for accessibility
  • Crop the image to fit the layout
  • Resize the image by dragging the handles on the right or bottom edge of the image
  • Adjust settings in the block toolbar and block settings sidebar
  • Apply styles to match the design system

When adding an image, you can choose how to bring it into the page:

  • Upload: Select a file from your computer
  • Media Library: Choose an existing image or upload a new one (most common)
  • Insert from URL: Use an external image link.
  • Drag and drop: Drop an image directly into the block

Note: Images added from external URLs may stop displaying if the source becomes unavailable. In most cases, it’s best to upload images to your Media Library.

Block toolbar

The block toolbar appears above the Image block when it’s selected.

Available options

  • Apply duotone: Apply color treatments to the image (for example, black and white or brand colors). Also available in the Styles tab.
  • Link: Make the image clickable by adding a URL
  • Crop: Crop the image directly in the editor
  • Scroll to zoom in or out
  • Click Apply in the toolbar to save changes
  • Add text over image: Converts the Image block into a Cover block
  • Add caption: Adds a caption field below the image
  • Caption text includes its own formatting toolbar (bold, italic, link)
  • Block width: Control how wide the image container is within the layout
  • Replace: Open the Media Library to swap the image without removing the block
  • Set as featured image: Located in Options (three-dot menu). Assign the image as the page or post’s featured image

Block settings

Block settings appear in the right sidebar while the Image block is selected.

Alt text

Describes the purpose of the image for screen readers. Add a clear, concise description of what the image conveys. You can also manage alt text in the Media Library.

Note: Alt text is not needed for purely decorative images.

Aspect ratio

Applies a predefined crop ratio (for example, 16:9 or 1:1 square). This is helpful for keeping multiple images visually consistent, especially when used in Columns or grid layouts.

Width and height

Controls the displayed dimensions of the image. By default, both are set to Auto, which is recommended. You can override these values if you need more control over sizing.

Scale

Controls how the image fits within a defined aspect ratio.

  • Cover: Fills the entire space (may crop the image)
  • Contain: Shows the full image within the space (may leave empty space)

Resolution

Selects which version of the image to display. Options typically include Thumbnail, Medium, Large, and Full Size. Choose the size based on how large the image appears on the page to balance visual quality and performance.

Block styles

In the Styles tab of the right sidebar, you can adjust the image’s visual appearance.

Styles

  • Default: Standard image display
  • Rounded: Applies rounded corners
  • Circle: Displays the image as a circle (best with square images)

Filters

Apply color filters to the image. Useful for creating stylistic treatments like black and white. Can help align images with brand colors.

Dimensions

Margin: Adds space around the image. Commonly used for top and bottom spacing. Helps separate images from surrounding content.

Shadow

Applies a drop shadow. Use sparingly to create subtle depth.

Border

Adds a border around the image. Control both border width and color.

Border radius

Applies custom corner rounding. Overrides Rounded or Circle styles when used.

Accessibility and content structure

Images are visual, but they still need accessible context.

Alt text best practices

  • Describe the purpose of the image, not just what it looks like
  • Keep descriptions concise and meaningful
  • Avoid phrases like “image of” or “picture of”

When alt text is not needed

  • Decorative images that don’t add meaning can have empty alt text
  • This prevents screen readers from announcing unnecessary content

Image usage and accessibility

  • Don’t rely on images alone to convey important information
  • Ensure text within images is also available as real text when possible

Thoughtful image use improves accessibility for everyone — including screen reader users and people with visual impairments.

Tips for editors

Use the media library when possible

Uploading images to the Media Library keeps assets organized and ensures they remain available. Avoid relying on external URLs unless necessary.

Choose the right image size

Large images can slow down your page. Use the Resolution setting to match the display size.

Keep images consistent

When using multiple images together (like in Columns), use the same Aspect ratio for a clean, aligned layout.

Don’t use images for layout

Images should support content — not be used to create spacing or structure. Use layout blocks and spacing controls instead.

Crop with intention

Cropping can improve composition, but make sure important parts of the image aren’t cut off — especially on smaller screens.

Please note that your implementation may include customizations that affect available settings or behavior.