Download the PHP package webfer/custom_bootstrap_icon_font without Composer

Custom Icon Font Builder (Bootstrap Icons + Font Awesome Free → WOFF2) for Drupal

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.

📦 Module Overview

• Name: Custom Bootstrap Icon Font
• Package: Media
• Compatibility: Drupal 10, 11

This module:

• Provides an admin page to select icons and configure the build.
• Builds the font either via Drush (recommended) or via a UI button (handy for local/dev).
• Writes generated assets to public://custom_bootstrap_icon_font/font/.
• Automatically attaches the generated CSS on the frontend (only if it exists).
• Provides Twig helpers to render icon markup.

Key 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.

🛠 Installation

✅ Install with Composer (recommended) 🧰

From your Drupal project root:

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, or
• 💻 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

✅ 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.
   • Note: some hosts do not allow writing to DRUPAL_ROOT/libraries from the web UI; in that case upload via SFTP/CI.
4. 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):

Alternative (global install):

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).
• Use the Icons preview section to browse your selected icons.
  • The preview is paginated (configure Icons per page on the form).

Optional: Upload SVG icons from the UI

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

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

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) 🖱️

1. Click Save and build now.
2. 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) 🧑‍💻

Aliases are kept for backwards compatibility:

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:

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:

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

🧱 Fantasticon specification

This module is a thin wrapper around the Fantasticon CLI.

Inputs

• Bootstrap Icons list: stored in custom_bootstrap_icon_font.settings:bootstrap_icons
• Font Awesome list: stored in custom_bootstrap_icon_font.settings:fontawesome_icons
  • Backwards compatibility: older installs may still have a merged custom_bootstrap_icon_font.settings:icons list; the build keeps it in sync.
• Bootstrap Icons source directory: stored in custom_bootstrap_icon_font.settings:icons_source_dir
  • Default: libraries/bootstrap-icons/icons (relative to DRUPAL_ROOT)
• Font Awesome source directory: stored in custom_bootstrap_icon_font.settings:fontawesome_icons_source_dir
  • Default: libraries/fontawesome/icons (relative to DRUPAL_ROOT)
• Generator command: stored in custom_bootstrap_icon_font.settings:generator_command
  • Default: npx fantasticon
  • Note: it is split on whitespace (simple tokenization). If you need complex quoting, use a small wrapper script and point generator_command at it.

Generated Fantasticon config

During drush di-font:build, the module stages the selected SVGs into a temporary folder and generates a Fantasticon JSON config equivalent to:

Important details:

• codepoints are provided explicitly to keep glyphs stable between builds.
• Only the currently selected icons are emitted into the font/CSS, but the module keeps a historical mapping in config so re-adding an icon later can reuse the same codepoint.
• normalize/fontHeight/descent are set to keep icon sizes consistent when mixing Bootstrap Icons (typically 16×16 viewBox) with Font Awesome (typically 512×512 viewBox).

Outputs

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

• <font_name>.woff2
• <font_name>.woff (optional fallback)
• 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:

🚨 Troubleshooting

• “Icon not found: …”

  • For Bootstrap Icons: confirm the icon exists in your Bootstrap Icons version. Example: youtube.svg should exist.
  • For Font Awesome: confirm the SVG exists under web/libraries/fontawesome/icons.
  • Some downloads have non-canonical filenames; the module attempts a best-effort match, but it’s still safest to keep filenames close to the icon name (example: arrow-down.svg).
  • Ensure the configured source directories exist:
  • icons_source_dir (recommended: web/libraries/bootstrap-icons/icons)
  • fontawesome_icons_source_dir (recommended: web/libraries/fontawesome/icons)

• Build fails

  • Ensure Node.js + npm + npx are installed.
  • Ensure Fantasticon is available on PATH (or set generator_command accordingly).
  • Run the build from the same environment where drush runs.
  • If you use the UI build, confirm the web/PHP user can run the generator command and that the request won’t time out.

• I clicked “Save configuration” but nothing was generated

  • That button only saves settings.
  • To generate the CSS + fonts, click Save and build now (or run drush di-font:build).

• CSS loads but icons show as empty squares

  • Font files are missing or blocked. Check the network tab for .woff2.
  • Confirm the CSS and fonts are in the same directory (so relative ./<font>.woff2 resolves).
• Icons changed after regeneration
  • Stable glyphs require stable codepoints. This module stores codepoints in config; avoid deleting that config between runs.

📂 File Structure

📜 License

This project is licensed under the GNU General Public License, version 2 or (at your option) any later version.

• SPDX identifier: GPL-2.0-or-later
• Created by: WebFer

_Created and maintained by WebFer