---
url: 'https://dxpr.com/hc/documentation/learn-dxpr-builder/development/hooks-api'
title: 'Hooks API reference | 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: 'Alter hooks for utility classes, icon sets and the field render array'
tags:
  - 'Architecture and APIs'
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: 'Hooks API reference'
      description: 'Alter hooks for utility classes, icon sets and the field render array'
      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/hooks-api'
      articleSection: 'Architecture and APIs'
    -
      '@type': WebPage
      '@id': 'https://dxpr.com/hc/documentation/learn-dxpr-builder/development/hooks-api'
      description: 'Alter hooks for utility classes, icon sets and the field render array'
      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) /[Architecture and APIs](/hc/documentation/learn-dxpr-builder/extend/architecture) # Hooks API reference.

Alter hooks for utility classes, icon sets and the field render array

 Learn DXPR BuilderExtendArchitecture and APIs

   ## In this guide

 Related guides

- [Permissions reference](/hc/documentation/learn-dxpr-builder/development/permissions)
- [API reference](/hc/documentation/learn-dxpr-builder/development/api)

DXPR Builder has five hooks. `dxpr_builder.api.php` documents all five, with an example of each.

| Hook | Invoked from | Effect |
|---|---|---|
| `hook_dxpr_builder_classes_alter(&$classes)` | `DxprBuilderService::editorAttach()` | Adds classes to the **HTML classes** list in the editor |
| `hook_dxpr_builder_icon_sets_alter(array &$icon_sets)` | `DxprBuilderService::getIconSets()` | Adds, changes or removes icon sets in the icon picker |
| `hook_dxpr_builder_view_elements(array &$element)` | `DxprBuilderFormatter::viewElements()` | Alters the render array of every field shown with the DXPR Builder formatter |
| `hook_dxpr_builder_element_buttons_folders_alter(&$folders)` | `DxprBuilderService::getButtonStyles()` | No visible effect; see below |
| `hook_dxpr_builder_elements_folders_alter(&$folders)` | `DxprBuilderService::getDxprElementsFolders()` | No visible effect; see below |

## hook\_dxpr\_builder\_classes\_alter

Adds entries to the class list that the **HTML classes** field of every element offers. The code invokes it through `$this->moduleHandler->alter('dxpr_builder_classes', ...)`, so the function name ends in `_alter`; a function named `mymodule_dxpr_builder_classes()` is never called.

```php
/**
 * Implements hook_dxpr_builder_classes_alter().
 */
function mymodule_dxpr_builder_classes_alter(&$dxpr_builder_classes) {
  // Start a new option group.
  $dxpr_builder_classes['optgroup-brand'] = t('Brand styles');
  $dxpr_builder_classes['brand-primary-bg'] = t('Primary background');
  $dxpr_builder_classes['brand-accent-text'] = t('Accent text colour');
}

```

- `&$dxpr_builder_classes` (array): the key is one class name, or several separated by spaces; the value is the label. A key that starts with `optgroup-` starts an option group.

The array already holds the classes of every enabled theme that sets `dxpr_builder_classes` in its `.info.yml`, so a theme needs no PHP. See [Utility classes](/hc/documentation/learn-dxpr-builder/customization/utility-classes).

## hook\_dxpr\_builder\_icon\_sets\_alter

Runs after the module has merged every `*.dxpr_icon_sets.yml` file of the enabled modules and themes. Prefer the YAML file; use the hook when the list depends on runtime logic.

```php
/**
 * Implements hook_dxpr_builder_icon_sets_alter().
 */
function mymodule_dxpr_builder_icon_sets_alter(array &$icon_sets) {
  $module_path = \Drupal::service('extension.list.module')
    ->getPath('mymodule');
  $icon_sets['material'] = [
    'label' => t('Material Symbols'),
    'prefix' => 'material-symbols',
    'css' => $module_path . '/vendor/material-symbols.css',
    'library' => 'mymodule/material_symbols',
    'icons' => [
      'material-symbols material-symbols-star',
      'material-symbols material-symbols-home',
    ],
  ];
}

```

The hook runs after relative `css` paths from the YAML files have been resolved, so a set added here needs a path from the Drupal root, as in the example. The keys of an icon set and the 14 built-in sets are listed on [Custom icon sets](/hc/documentation/learn-dxpr-builder/development/icon-sets).

## hook\_dxpr\_builder\_view\_elements

Invoked with `invokeAll()` at the end of `DxprBuilderFormatter::viewElements()`, after the formatter has attached its libraries, settings and profile. `$element` is the field's render array, passed by reference. It runs for every viewer, editor or not.

```php
/**
 * Implements hook_dxpr_builder_view_elements().
 */
function mymodule_dxpr_builder_view_elements(array &$element) {
  $element['#attached']['library'][] = 'mymodule/builder_extras';
}

```

## Hooks without a visible effect

- `hook_dxpr_builder_element_buttons_folders_alter()` receives a list of folders whose `.html` files describe button styles. The result reaches `drupalSettings.dxprBuilder.buttonStyles`. The Button element reads its own fixed list of Bootstrap styles instead, so extra folders change nothing in the editor.
- `hook_dxpr_builder_elements_folders_alter()` would alter a list of `elements` folders in themes, but nothing calls `getDxprElementsFolders()`, so the hook never runs. It does not register elements; to add one, see [Custom elements](/hc/documentation/learn-dxpr-builder/development/custom-elements).

## What's next?

- [Permissions](/hc/documentation/learn-dxpr-builder/development/permissions) for the permissions the module defines.
- [API reference](/hc/documentation/learn-dxpr-builder/development/api) for the services and routes.