Custom icon sets

The icon picker offers 14 built-in icon sets. You add your own with a YAML file in your module or theme, or change the list with an alter hook. The module merges every *.dxpr_icon_sets.yml file it finds in enabled modules and themes, then runs the hook.

Built-in sets

From dxpr_builder.dxpr_icon_sets.yml:

Key	Label	Prefix
`bi`	Bootstrap Icons	`bi`
`et`	ET Line Icons	`et`
`fa`	Font Awesome (v4 compatibility)	`fa`
`fab`	Font Awesome Free Brands	`fab`
`far`	Font Awesome Free Regular	`far`
`fas`	Font Awesome Free Solid	`fas`
`glyphicon`	Glyphicon Halflings	`glyphicon`
`pe`	Pixeden Line Icons	`pe`
`ph`	Phosphor Icons Regular	`ph`
`ph_bold`	Phosphor Icons Bold	`ph-bold`
`ph_duotone`	Phosphor Icons Duotone	`ph-duotone`
`ph_fill`	Phosphor Icons Fill	`ph-fill`
`ph_light`	Phosphor Icons Light	`ph-light`
`ph_thin`	Phosphor Icons Thin	`ph-thin`

A builder profile can limit which sets its editors see (Icon sets on the profile form).

YAML discovery (recommended)

Create mymodule.dxpr_icon_sets.yml in the root of your module or theme:

material:
  label: 'Material Symbols'
  prefix: material-symbols
  css: vendor/material-symbols/material-symbols.css
  library: mymodule/material_symbols
  icons:
    - 'material-symbols material-symbols-star'
    - 'material-symbols material-symbols-home'
    - 'material-symbols material-symbols-search'

A set with the same key as an earlier one replaces it.

Properties

Property	Required	Description
`label`	Yes	Name in the icon set dropdown; the key is used when it is missing
`prefix`	Yes	CSS class prefix that identifies icons of this set
`css`	Yes	Stylesheet the editor loads; a relative path is resolved from your module or theme root
`library`	Yes	Drupal library attached for visitors when saved content uses this set
`icon_prefix`	No	Prefix of the icon name when it differs from `prefix`, as in `fas fa-heart`
`icons`	Yes*	Full list of icon classes

*The built-in sets omit icons; the editor has their lists in JavaScript. Your own set must list every icon.

Drupal library definition

Register the stylesheet as a library in mymodule.libraries.yml, so visitors get it on pages that use your icons:

material_symbols:
  css:
    theme:
      vendor/material-symbols/material-symbols.css: {}

The module attaches a library with a / in its name only when it is the library of a registered icon set.

Alter hook

For runtime logic, such as adding a set only under some condition, implement hook_dxpr_builder_icon_sets_alter(). The hook runs after YAML paths are resolved, so give css a path from the Drupal root:

/**
 * Implements hook_dxpr_builder_icon_sets_alter().
 */
function mymodule_dxpr_builder_icon_sets_alter(array &$icon_sets) {
  if (some_condition()) {
    $module_path = \Drupal::service('extension.list.module')
      ->getPath('mymodule');
    $icon_sets['custom'] = [
      'label' => t('Custom Icons'),
      'prefix' => 'ci',
      'css' => $module_path . '/css/custom-icons.css',
      'library' => 'mymodule/custom_icons',
      'icons' => ['ci ci-logo', 'ci ci-arrow'],
    ];
  }
}

See Hooks API reference for the other hooks.

Removing built-in sets

/**
 * Implements hook_dxpr_builder_icon_sets_alter().
 */
function mymodule_dxpr_builder_icon_sets_alter(array &$icon_sets) {
  // Remove ET Line Icons from the picker.
  unset($icon_sets['et']);
}

Check your set

Clear the cache: drush cr.
Open a page in the builder and add an Icon element.
Open the icon picker and choose your set in the dropdown.
Pick an icon, save, and view the page as a visitor to confirm the icon renders.

Something wrong or missing on this page? Report it or edit the page.