Icon Picker Block

The Icon Picker block lets you add a single, flexible icon to your page. It’s ideal for visual accents, and lightweight content elements that support surrounding text.

This block is fully managed from the block settings sidebar, making it easy to control the icon, colors, and size in one place.

Why use the Icon Picker block

Use the Icon Picker block when you want to:

  • Add a visual cue next to content (like checkmarks, arrows, or indicators)
  • Reinforce meaning or hierarchy without adding extra text
  • Keep icon usage consistent with your site’s design system
  • Control icon appearance without custom styling or markup

Icons work best when they support content — not replace it. This block helps you do that intentionally.

How to use the block

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

Once the block is added, editors typically:

  • Select an icon from the available icon set
  • Add an accessible label to describe the icon’s meaning
  • Adjust colors and size to fit the surrounding content
  • Use padding or rounding to match the intended visual treatment

All configuration for this block happens in the block settings sidebar.

Block toolbar

The Icon Picker block does not include toolbar controls above the block.
All configuration options are managed in the block settings sidebar.

Block settings

When the Icon Picker block is selected, all settings appear in the right sidebar. The settings are organized into three tabs: Icon, Colors, and Dimensions.

Icon tab

Search icons

Choose the icon you want to display.

  • Browse all available icons using the thumbnail grid
  • The available icons are set by the design system. Icons cannot be directly added within the block, but the block can be extended by development to add more custom icons.
  • Scroll to view the full icon set
  • Use the search field to narrow results by keyword
  • Select an icon to apply it to the block
  • Select a different icon at any time to change it

Once selected, the icon will appear immediately in the editor.

Custom label

Adds an accessible text label for the icon.

This label is not visually displayed, but it helps screen reader users understand the purpose of the icon.

Tip: Use a short, descriptive label that explains what the icon represents, not how it looks.

Colors tab

Icon color

Controls the color of the icon itself.

  • Choose from predefined color swatches
  • Or, click the color field to open the full color picker
  • You can select a color visually or enter a specific color value

Background color

Controls the background color behind the icon.

  • Uses the same color picker and swatches as Icon color
  • Especially useful when pairing with padding or a rounded icon

Accessibility note: Make sure there is sufficient contrast between the icon color and the background color.

Dimensions tab

Container padding

Adds space inside the icon container, around the icon itself.

  • Set a pixel value
  • Useful for creating breathing room or touch-friendly spacing

Container size

Sets the overall size of the icon container.

  • Choose a pixel value to define the width
  • The icon scales proportionally within the container

Rounded icon

Makes the icon container into a circle.

  • Best used with a background color applied
  • Ideal for badges, indicators, or decorative icon treatments

Accessibility and content structure

Icons are visual by nature, but they still need accessible context.

To keep icons accessible:

  • Always add a Custom label when the icon conveys meaning
  • Use icons to support text, not replace important information
  • Ensure sufficient color contrast between icon and background

When used thoughtfully, icons improve clarity for everyone — including screen reader users.

Tips for editors

Don’t rely on icons alone

Icons shouldn’t be the only way information is communicated.
Pair icons with text or ensure the Custom label clearly explains the icon’s purpose.

Keep icon usage consistent

Too many different icon styles or sizes can feel cluttered.
Reuse similar icon treatments across a page or section for a cleaner experience.

Use color intentionally

Color can enhance meaning, but it can also reduce readability if overused.
Check contrast and avoid using color as the only indicator of meaning.

Size for context

Oversized icons can overwhelm content, while tiny icons can feel unclear.
Adjust container size and padding so the icon feels balanced with nearby text.