Add a live library image in Gutenberg

Use the POM Image block to display a media-library image with the theme's image layouts, overlays, hover images and click actions. This guide is for content editors using Gutenberg with POM active.

Add an image

1. Open Pages → All Pages or Posts → All Posts, then edit your content in Gutenberg.
2. Open the block inserter and choose POM's Image block. Its description mentions live media-library images and theme overlays.
3. Choose or upload an image using the media picker.
4. In Image source, choose Image size, alignment and optional dimensions. You can also use the floating alignment toolbar.
5. Save the page and use the frontend preview to review the result.

The block can sit directly in the document or inside a POM Section or Column. It does not require an additional Row wrapper.

Keep metadata current

Library images use their current alternative text, title, caption, description, destination link, responsive sources and dimensions when the page renders. The block does not save independent copies of these values.

Use Edit image metadata in the library to update the attachment. Return to Gutenberg and choose Refresh library preview in the floating toolbar. You do not need to save the page again merely to update its image metadata on the frontend.

A cached HTML page can still show previous metadata until the relevant page cache is purged or expires. Changing metadata does not automatically purge every external cache.

Write alternative text that describes the image's purpose. An empty alternative text marks an ordinary image as decorative. Because library alt text is shared, changing it affects every POM Image that uses that attachment.

An external Attachment ID or image URL value uses the basic legacy image layout. Supply its Alternative text in the block. External URLs do not supply library metadata, responsive sources or the library-only overlay and interaction controls.

Layout and overlay

• Fit image to parent width uses the existing theme fit helper. Leave Custom width (px) and Custom height (px) empty for the selected image size. Setting only one preserves the image ratio.
• Overlay → Display overlay offers None, On hover, Hide on hover and Always.
• Choose a solid or bottom-gradient background, a numeric theme palette color and opacity in 10% steps. Text color uses the theme's existing palette classes.
• Set overlay alignment, an inset frame, hover zoom, and optional pointer-direction entry.
• Select title, caption, description, lightbox icon, linked title, link icon, button and an optional library icon. Titles, captions and descriptions come from the attachment.
• Preview overlay and Preview hover image change only the editor preview, not the saved behavior.

The editor uses the theme's image components without loading the entire frontend stylesheet. Click actions and GIF playback are reviewed in the frontend preview; editor preview links are intentionally inactive so they do not interrupt editing.

Use Replace image in the floating block toolbar for quick media selection. The editor resolves lazy image sources without running frontend interaction scripts. Use Refresh library preview after editing attachment metadata.

Click actions

Click actions → Whole image action can do nothing, enlarge the image in a lightbox, open an existing modal, use the attachment's destination link, or control an existing slider.

The overlay title, link icon and button have their own action setting, shown only when an enabled overlay contains an actionable element. Link the title is available when the title is enabled. Disabling the overlay retains its choices but does not load a modal solely because of its previous action. The lightbox icon always enlarges the image. Link destinations and new-tab preferences come from the media-library metadata.

For a modal, provide its existing Modal box ID, without #. For a slider, choose its ID and next, previous or custom slide action. The image does not create these targets. The target carousel owns its slider assets.

You can create the dialog with a Modal block and copy its Modal ID into the Image action.

Lightbox dimensions normally come from the original image; use the width and height overrides only when needed. Show description in lightbox includes the attachment description.

Hover, GIF and SVG

Hover image lets you choose a second library image. Its alternative text is also read from the library.

For GIFs, GIF playback → Playback offers unmodified output, autoplay, hover, click and viewport playback. Choose a Static GIF thumbnail for modes that need to stop the animation. A GIF without a still frame cannot visually return to a non-animated image.

Render SVG inline applies only to local SVG attachments. POM sanitizes the SVG before embedding it. Other image types remain ordinary image elements.

Performance and visibility

Performance exposes loading behavior and fetch priority. High priority forces eager loading; reserve it for an important image above the fold. Lazy loading follows the theme's lazy-load setting.

Visibility controls desktop, tablet landscape, tablet portrait and mobile independently, using the theme's 992/768/576px boundaries. Hidden blocks remain selectable in the editor.

CSS classes → Additional CSS classes accepts existing helpers on the image container, including for external images. Advanced → HTML anchor sets an explicit identifier. Neither creates arbitrary frontend CSS; overlay backgrounds use the page's generated CSS.

Verify and troubleshoot

1. Save, reload the editor and confirm the chosen image and settings remain.
2. Review alignment and width at all four device sizes.
3. Open the frontend preview and exercise lightbox, modal, slider or GIF behavior as applicable.
4. If library metadata appears old, refresh the editor preview and clear the relevant frontend cache.
5. If the image is unavailable, select an existing public image attachment. If an interaction does nothing, check its target ID and that the target exists on the page.

Related: Gutenberg buttons, device visibility, and the legacy Image shortcode.