custom_bootstrap_icon_font

A Drupal module that generates a custom icon font (WOFF2 + optional WOFF) from a selected subset of Bootstrap Icons and/or Font Awesome Free SVGs, and publishes matching CSS classes.

Why? Keep your frontend lightweight: instead of shipping entire icon sets, you can select only the icons your site actually uses and generate a small, focused font + CSS just for those.

Features

• Split icon configuration by source
  • Separate lists for Bootstrap Icons and Font Awesome Free.
• Select icons by name, by class, or by pasted HTML snippets
  • Bootstrap accepts lines like
    arrow-right-circle-fill,
    bi-arrow-right-circle-fill,
    bi bi-arrow-right-circle-fill, or
    <i class="bi bi-arrow-right-circle-fill"></i>.
  • Font Awesome accepts lines like
    <i class="fa-solid fa-arrow-down"></i>,
    fa-arrow-down, or
    fa-solid-arrow-down.
• Stable glyph codepoints across rebuilds
  • Codepoints are stored in config so previously-used icons keep the same Unicode value when re-added.
• Bootstrap-like CSS output
  • Generates a small CSS file that maps
    .di-<icon> to a glyph via
    ::before { content: "\\e001"; }.
• Composer/CI friendly
  • Bootstrap Icons live in web/libraries/bootstrap-icons/icons.
  • Font Awesome SVGs live in web/libraries/fontawesome/icons.
  • Fantasticon is installed at the project level (or globally) and executed via Drush.

Post-Installation

Install with Composer (recommended)

From your Drupal project root:

composer require webfer/custom_bootstrap_icon_font

Composer will install the module into your Drupal codebase
(commonly under web/modules/contrib/ in standard Drupal Composer templates).

Then enable the module:

• Admin > Extend → enable Custom Bootstrap Icon Font
• drush en custom_bootstrap_icon_font -y

Install without Composer (development only)

If you’re developing locally, you can still place the module folder under:

web/modules/custom/custom_bootstrap_icon_font

Additional Requirements

Drupal

• Drupal core 10/11.
• Ability to write to public://
  (this module stores generated assets under
  public://custom_bootstrap_icon_font/).

Bootstrap Icons SVG sources

The build needs access to the Bootstrap Icons SVG files
(*.svg).

Recommended location (Drupal libraries):

web/libraries/bootstrap-icons/icons

You can install Bootstrap Icons there by either:

• Downloading a release from
  https://github.com/twbs/icons/releases
  and extracting to web/libraries/bootstrap-icons, or
• Using a build/CI step to fetch it.

Font Awesome Free SVG sources

Font Awesome icons are not bundled by this module.
You provide the SVGs.

Recommended location (Drupal libraries):

web/libraries/fontawesome/icons

Where to obtain icons:

• Browse/search the Free collection:
  https://fontawesome.com/search?ic=free

Recommended workflow:

1. Find an icon in the Free collection.
2. Download the SVG.
3. Upload it into
   web/libraries/fontawesome/icons.
   You can use the admin UI “Upload SVG icons (optional)” section.
4. Note: some hosts do not allow writing to
   DRUPAL_ROOT/libraries from the web UI;
   in that case upload via SFTP/CI.
5. Paste the corresponding snippet into the Font Awesome list
   (example:
   <i class="fa-solid fa-arrow-down"></i>).

Node tooling (required for building assets)

Asset generation uses Fantasticon, typically via
npx fantasticon.

You need:

• node, npm, npx
• Fantasticon available to the same environment that runs
  drush.

Tip 💡: If you plan to build from the admin UI
(“Save and build now”), the same Node tooling must also be
available to the PHP/web user, and the request must be allowed
to run long enough.

Recommended (project-level, deterministic):

cd /path/to/project/root  # the folder you run drush from

# Only needed if you don't already have a root package.json.
npm init -y

npm install --save-dev fantasticon

# Verify it is available without prompting/downloading.
npx --no-install fantasticon --version

Alternative (global install):

npm install -g fantasticon
fantasticon --version

Important:

• If Fantasticon is not installed locally/globally,
  npx fantasticon may try to download it interactively
  (not suitable for non-interactive servers/CI).
• If you use Yarn or pnpm, install Fantasticon in your project
  and set generator_command accordingly.

Configuration

1. Permissions

   The admin UI requires:

   • Permission: administer custom bootstrap icon font
   • Assign it under People > Permissions.
2. Build / update the font

   Go to:

   • Admin path: /admin/config/media/bootstrap-icon-font

   On this page you can:

   • Enter Bootstrap icons (one per line). Names may include or omit the bi- prefix; it is normalized automatically.
   • You can also paste full HTML snippets and the module will extract the icon name automatically (example: <i class="bi bi-basket-fill"></i>).
   • Enter Font Awesome Free icons (one per line). Paste snippets like <i class="fa-solid fa-arrow-down"></i> or use shorthand fa-arrow-down / fa-solid-arrow-down. Ensure the matching SVG exists under web/libraries/fontawesome/icons (see Requirements above).
   • Pick a font_name (the font-family name used in CSS).
   • Configure where Bootstrap Icons live (icons_source_dir).
   • Configure where Font Awesome SVGs live (fontawesome_icons_source_dir).
   • Configure the generator command (generator_command).

   Optional: Upload SVG icons from the UI

   The admin page also includes an "Upload SVG icons (optional)" section.

   1. Upload one or more .svg files (they are stored temporarily).
   2. Click Copy uploaded SVGs into libraries/ to copy them into either:
      • web/libraries/fontawesome/icons (recommended for Font Awesome)
      • Your configured Bootstrap Icons source directory

   Note: If your server does not allow writing to DRUPAL_ROOT/libraries from PHP, upload icons via SFTP/CI instead.

   Build assets (two options)

   Option A: Build from the UI (friendly)

   Click Save and build now. The module generates the CSS + font files under public://custom_bootstrap_icon_font/font/. This is great for local/dev. On production, Drush is usually safer (no web timeouts and doesn’t require Node to run during a web request).

   Option B: Build via Drush (recommended)

   drush di-font:build

   Aliases are kept for backwards compatibility:

   • drush custom-bootstrap-icon-font:build
   • drush ci-font:build
   • drush cbi-font:build

   When the build completes, the module:

   • Saves the selected icons to config (custom_bootstrap_icon_font.settings).
   • Maintains a stable codepoints mapping so glyphs don’t change between regenerations.
   • Writes:
     • public://custom_bootstrap_icon_font/font/<font_name>.woff2
     • public://custom_bootstrap_icon_font/font/<font_name>.woff (optional)
     • public://custom_bootstrap_icon_font/font/custom-bootstrap-icon-font.css
   • Updates version for cache-busting.
   • Invalidates render cache.

Usage

Option A: CSS classes (Bootstrap-like)

After generating assets, you can render icons using classes and a pseudo-element:

• <span class="di di-arrow-right-circle-fill" aria-hidden="true"></span>
• <span class="di di-fa-solid-arrow-down" aria-hidden="true"></span>
• <span class="di-youtube" aria-hidden="true"></span>

Notes:

• The generated CSS includes Bootstrap-icons style selectors:
  .di::before, [class^="di-"]::before, [class*=" di-"]::before { ... }
• The icon is rendered by ::before { content: "\\e001"; }.

Option B: Twig helper

This module provides:

• {{ di_font_icon('arrow-right-circle-fill') }}
• {{ di_font_icon('fa-solid-arrow-down') }}
• {{ di_font_icon('youtube', { class: 'text-danger me-2' }) }}

Backwards-compatible Twig function names are also available (if you used older templates):

• {{ ci_font_icon('arrow-right-circle-fill') }}
• {{ cbi_font_icon('arrow-right-circle-fill') }}

Outputs

Files written to public://custom_bootstrap_icon_font/font/:

• <font_name>.woff2
• <font_name>.woff
• custom-bootstrap-icon-font.css (uses relative <font_name>.woff2?v=<version> URLs)

Styling

Because this is a font:

• Icon color is controlled by color.
• Icon size is controlled by font-size.

Example:

.di,
[class^='di-'],
[class*=' di-'] {
  color: currentColor;
}

Maintainers

Created and maintained by WebFer