Add a theme icon in Gutenberg

Use Icon to display one SVG from a theme icon library, with an optional link. It uses the same appearance as the Page Builder Icon component. To place several paragraphs, headings, or lists beside an icon, use Icon Box instead.

You need permission to edit the page, the POM theme active, and an available theme icon library.

Add and style an icon

  1. Open Pages → Add Page, or edit an existing page in the block editor.
  2. Open the block inserter, search for Icon, and choose the POM Icon block. It is also available in Design.
  3. Click Select Icon in the block's Icon settings and choose an icon from a library.
  4. Set Icon size to Small, Normal, Large, or Adapt width to parent container. The first three scale with the inherited text size; Adapt width to parent container fills the available width.
  5. Choose Icon background shape, Icon color, and Icon background. Colors are theme palette slots. Click the selected swatch again to clear that setting.
  6. Use the alignment control in the floating block toolbar to align the icon left, center, or right.

The canvas previews the selected SVG, size, shape, and palette colors immediately. Change Icon replaces it; Remove clears it without deleting the block. An empty Icon block displays an editor placeholder and no visible icon on the published page.

In the block settings, open Link and accessibility:

  1. Enter Icon link using an https:// or http:// URL, a relative path, an anchor such as #contact, mailto:, or tel:.
  2. Enter an Accessible name describing the destination, such as “Contact our team.” If this is empty, the URL is used as the link name.
  3. Enable Open in new tab or Add nofollow to link only when needed. New-tab links also receive noopener noreferrer.

Without a link, Decorative icon is enabled by default. Leave it on if nearby text already explains the icon. Turn it off and provide an Accessible name if the icon communicates information on its own.

Links do not navigate away from the editing canvas. Check their destination in the page preview.

For existing integrations, Additional link attributes accepts quoted name="value" pairs, separated by spaces or new lines:

title="Contact our team"
data-tracking="contact-icon"

Supported names are title, download, hreflang, data-* except data-wp-*, aria-description, aria-describedby, and aria-details. Limit the field to 32 attributes and 4,096 characters. Unsupported or malformed attributes produce a warning and are omitted from the link. Event handlers, inline CSS, and overrides for the link destination, target, relationship, or accessible name are not accepted.

Visibility, identifiers, and existing helpers

  • Visibility controls Desktop (992px and wider), Tablet Landscape (768–991px), Tablet Portrait (576–767px), and Mobile (575px and narrower). A hidden icon remains selectable under a visibility overlay in the editor.
  • Advanced → HTML anchor sets a unique HTML identifier.
  • CSS classes → Additional CSS classes adds existing helpers, separated by spaces. It does not create CSS.

The block saves basic HTML with existing theme classes and its SVG. It does not add a frontend stylesheet or script. Palette values follow the current theme colors; changing an icon library file does not replace SVGs already saved in content—select the icon again to update one.

Verify the result

Save the page and reload the editor. Confirm the icon and settings remain unchanged. Open the page preview, check each relevant screen size, and follow linked icons using both mouse and keyboard.

If selection fails, choose another icon from an available theme library and try again; the previous icon is retained. If the block appears empty, check that an icon is selected and that its colors contrast with the page background. If it disappears only on one device, review Visibility.

Style native Gutenberg headings
Previous
Build an accordion in Gutenberg
Next