---
url: 'https://dxpr.com/hc/documentation/learn-dxpr-builder/development/icon-sets'
title: 'Custom icon sets | DXPR'
author:
  name: docs-sync
  url: 'https://dxpr.com/users/docs-sync'
date: '2026-10-23T14:31:17+00:00'
copyright: 'Copyright DXPR. All rights reserved.'
type: article
summary: 'Add icon libraries through YAML discovery or a hook'
tags:
  - 'Build on it'
image: 'https://dxpr.com/themes/custom/dxpr_com/images/dxpr-share-card.jpg'
published: true
og:
  site_name: DXPR
  updated_time: '2026-10-23T14:31:17+0000'
  'image:alt': 'DXPR, powered by Drupal: AI-powered Drupal for marketers.'
schema:
  '@context': 'https://schema.org'
  '@graph':
    -
      mainEntity: {  }
    -
      '@type': TechArticle
      headline: 'Custom icon sets'
      description: 'Add icon libraries through YAML discovery or a hook'
      image:
        '@type': ImageObject
        url: 'https://dxpr.com/themes/custom/dxpr_com/images/dxpr-share-card.jpg'
        width: '1200'
        height: '630'
      datePublished: '2026-10-23T14:31:17+0000'
      dateModified: '2026-10-23T14:31:17+0000'
      author:
        '@type': Organization
        '@id': 'https://dxpr.com/#organization'
        name: DXPR
        url: 'https://dxpr.com/'
        logo:
          '@type': ImageObject
          url: 'https://dxpr.com/themes/custom/dxpr_com/dxpr-logo-dark.svg'
          width: '1348'
          height: '501'
      publisher:
        '@type': Organization
        '@id': 'https://dxpr.com/#organization'
        name: DXPR
        url: 'https://dxpr.com/'
        logo:
          '@type': ImageObject
          url: 'https://dxpr.com/themes/custom/dxpr_com/dxpr-logo-dark.svg'
          width: '1348'
          height: '501'
      mainEntityOfPage: 'https://dxpr.com/hc/documentation/learn-dxpr-builder/development/icon-sets'
      articleSection: 'Build on it'
    -
      '@type': WebPage
      '@id': 'https://dxpr.com/hc/documentation/learn-dxpr-builder/development/icon-sets'
      description: 'Add icon libraries through YAML discovery or a hook'
      breadcrumb:
        '@type': BreadcrumbList
        itemListElement:
          -
            '@type': ListItem
            position: 1
            name: Home
            item: 'https://dxpr.com/'
      publisher:
        '@type': Organization
        '@id': 'https://dxpr.com/#organization'
        name: DXPR
      inLanguage: en
---
[Help Center](/hc)/[Documentation](/hc/documentation) /[Learn DXPR Builder](/hc/documentation/learn-dxpr-builder) /[Extend](/hc/documentation/learn-dxpr-builder/extend) /[Build on it](/hc/documentation/learn-dxpr-builder/extend/build-on-it) # Custom icon sets.

Add icon libraries through YAML discovery or a hook

 Learn DXPR BuilderExtendBuild on it

   ## In this guide

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:

```yaml
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:

```yaml
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:

```php
/**
 * 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](/hc/documentation/learn-dxpr-builder/development/hooks-api) for the other hooks.

## Removing built-in sets

```php
/**
 * 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

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