Icon libraries

The icon picker in the Icon and Circle counter elements offers every icon set registered on your site. DXPR Builder ships 14 sets; modules and themes can add more with a YAML file. This page lists the shipped sets, explains how they load, and shows you how to add one. To limit the sets a role sees, use a builder profile; see User profiles.

Shipped icon sets

The sets are registered in dxpr_builder.dxpr_icon_sets.yml:

Key	Label in the picker	Class prefix	Library
`bi`	Bootstrap Icons	`bi`	`dxpr_builder/elements.bootstrap_icons`
`et`	ET Line Icons	`et`	`dxpr_builder/elements.et_line_font`
`fab`	Font Awesome Free Brands	`fab`	`dxpr_builder/elements.font_awesome_6_free`
`far`	Font Awesome Free Regular	`far`	`dxpr_builder/elements.font_awesome_6_free`
`fas`	Font Awesome Free Solid	`fas`	`dxpr_builder/elements.font_awesome_6_free`
`glyphicon`	Glyphicon Halflings	`glyphicon`	`dxpr_builder/elements.glyphicons_halflings`
`pe`	Pixeden Line Icons	`pe`	`dxpr_builder/elements.pe_icon_7_stroke`
`ph`	Phosphor Icons Regular	`ph`	`dxpr_builder/elements.phosphor_icons`
`ph_bold`	Phosphor Icons Bold	`ph-bold`	`dxpr_builder/elements.phosphor_icons_bold`
`ph_duotone`	Phosphor Icons Duotone	`ph-duotone`	`dxpr_builder/elements.phosphor_icons_duotone`
`ph_fill`	Phosphor Icons Fill	`ph-fill`	`dxpr_builder/elements.phosphor_icons_fill`
`ph_light`	Phosphor Icons Light	`ph-light`	`dxpr_builder/elements.phosphor_icons_light`
`ph_thin`	Phosphor Icons Thin	`ph-thin`	`dxpr_builder/elements.phosphor_icons_thin`
`fa`	Font Awesome (v4 compatibility)	`fa`	`dxpr_builder/elements.font_awesome_6_free`

The picker does not offer the fa set, because it has no icon list. It makes icons saved with the old fa class load the Font Awesome library. Pages saved with the old Font Awesome library names also get the dxpr_builder/elements.font_awesome_v4_shims stylesheet, so their icons keep showing.

All Font Awesome sets load Font Awesome Free 7. The library keeps its version 6 machine name, because saved pages and custom code refer to it. Font Awesome 7 in DXPR Builder lists what changed.

How the picker and pages load icons

The set dropdown starts with All icon sets, then lists every registered set that has an icon list. The 13 shipped sets other than fa have built-in lists, so a site with only DXPR Builder shows 14 entries. A set from another module or theme needs an icons list in its YAML to appear.

When an editor picks an icon, the element stores the icon's classes, such as bi bi-star, and the name of its library. Visitors then download only the icon fonts their page uses. In the editor, ET Line, Pixeden and Glyphicon load with the editor itself; the picker loads the other sets' stylesheets when it opens.

How editors choose and style an icon is on Adding an Icon.

Limit icon sets per role

Each builder profile has an Icon sets group with a box per set and a Check/Uncheck all Icon sets box. Configure it at DXPR Studio > DXPR Builder > User Profiles; User profiles has the steps. How the group behaves:

With Check/Uncheck all Icon sets ticked, the role sees every set, including sets added later.
With it unticked, the role sees only the ticked sets. A new profile starts this way, with every set ticked, so a set added later stays hidden until you tick it.
With it unticked and no set ticked, the picker is empty.
Icons already on a page keep showing. The profile only changes what the picker offers.

Add an icon set

An icon set is a YAML entry plus a Drupal library. DXPR Builder reads *.dxpr_icon_sets.yml from every installed module and theme. The property reference and the alter hook are on Custom Icon Sets.

Create mymodule/mymodule.dxpr_icon_sets.yml:

yaml brand: label: 'Brand icons' prefix: brand css: css/brand-icons.css library: mymodule/brand_icons icons: - 'brand brand-logo' - 'brand brand-arrow'

css is relative to the module's folder and loads in the editor. Each icon is the prefix plus a class that starts with the prefix and a hyphen.
Declare the library in mymodule.libraries.yml. Visitors' pages load it:

yaml brand_icons: css: theme: css/brand-icons.css: {}
Clear caches with drush cr.
Tick the new set in every builder profile that does not have Check/Uncheck all Icon sets ticked.
Open an Icon element's settings and choose Brand icons in the set dropdown.

A custom module can also remove a set from the picker with an alter hook; the code is on Hooks API reference. Icons from a shipped set keep loading on saved pages anyway. Icons from a removed custom set stop loading their CSS, because DXPR Builder only attaches a library that a registered set names.

If an icon set is missing

A new set is not in the dropdown. Its YAML has no icons list, or the cache still holds the old registry. Add the list and run drush cr.
A set is missing for some editors only. Their builder profile does not tick it. Tick it under Icon sets at /admin/dxpr_studio/dxpr_builder/profile.
Icons show in the editor but not for visitors. The editor loads the set's css file, but visitors' pages load its library. Make sure library names a library in mymodule.libraries.yml that contains the CSS file.

What's next?

Custom Icon Sets: the YAML property reference and the alter hook.
Adding an Icon: the Icon element's settings.

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