Options Icons

Options icons lets you show an icon next to each option of a List field. Site builders assign an icon to each allowed value, and editors then choose an option by its icon instead of only by its label.

A typical use case is a "Layout" or "Variant" field on a block, paragraph or content type, where editors pick a layout by its thumbnail. The theme then uses the stored value as a modifier.

The icons come from the Icon API in Drupal core, so you can use any icon pack defined by a module or theme, including your own SVG or PNG thumbnails.

Features

• An extra "Icon" column in the allowed values table of List (text), List (integer) and List (float) fields.
• A "Check boxes/radio buttons with icons" widget, which shows the icon with its label, or the icon only. With "icon only", the label is kept for screen readers.
• The icon size can be set per form display.
• Options without an icon just show their label.
• The stored value is a plain List value, so templates, Views and existing content keep working as before.
• Icons are stored in the field storage configuration, so they are exported with your config. Uninstalling the module removes them and leaves regular List fields.

Post-Installation

1. Make sure an icon pack is available. You can define one in your theme, for example in mytheme.icons.yml:
   

   mytheme_layouts:
     label: 'Layouts'
     extractor: path
     config:
       sources:
         - img/layouts/{icon_id}.png
     template: '<img src="{{ source }}" width="{{ size|default(64) }}" alt="">'

2. Add or edit a List field. Each row of the "Allowed values" table now has an "Icon" element. Choose an icon per allowed value and save.
3. On "Manage form display", set the widget of the field to "Check boxes/radio buttons with icons". In the widget settings you can choose between icon and label or icon only, and set the icon size.

Icons are configured per field storage, like the allowed values. So all bundles that share a field also share its icons. Allowed values provided by an allowed_values_function cannot have icons.

Additional Requirements

• Drupal 11.3 or later.
• Options and Field UI, both in Drupal core.

Note that the Icon API in Drupal core is still marked experimental.

Recommended modules/libraries

UI Icons: if installed, its form elements are used to choose the icons. With the UI Icons Picker submodule you get a visual icon picker, with only UI Icons you get an autocomplete. Without UI Icons, a select list of all icons is used, grouped by icon pack. UI Icons is recommended for sites with large icon packs.

Similar projects

• UI Icons Fields, part of UI Icons, provides an Icon field type, where editors can pick any icon per entity. Options icons instead ties a fixed icon to each allowed value of a List field, so editors choose from a limited set of options.