Installation

No build step?

If you cannot run a bundler — a content site, a prototype, or a CMS template — you can autoload components from an ESM CDN such as esm.sh with a short module script instead of installing the package.

In a Twig project

Requirements

• PHP 8.3 or higher
• Composer 2.x

Setup

Install the JavaScript package with NPM:

npm install @studiometa/ui

Install the Twig and PHP parts with Composer:

composer require studiometa/ui

The package is a Composer plugin that automatically fetches icons from the Iconify API when you run composer install or composer update. You will need to allow the plugin:

composer config allow-plugins.studiometa/ui true

Offline / CI environments

The plugin makes HTTP requests to the Iconify API during composer install and composer update to fetch icon SVGs. If your environment does not have internet access, you can disable automatic syncing and commit the fetched icons to your repository instead:

{
  "extra": {
    "studiometa/ui": {
      "icons": { "enabled": false }
    }
  }
}

Icon management

Icons referenced via meta_icon('collection:icon-name') in your templates are automatically scanned and fetched as local SVG files. Only the icons you actually use are downloaded — there is no need for the full iconify/json package (~690MB).

You can also manage icons manually:

# Scan templates and fetch missing icons
composer ui:icons

# Preview detected icons without fetching (dry-run)
composer ui:icons --dry-run

# Fetch and remove unused icons
composer ui:icons --prune

# Remove unused icons only
composer ui:icons:prune

Configuration

You can configure the icon behavior in your project's composer.json:

{
  "extra": {
    "studiometa/ui": {
      "icons": {
        "enabled": true,
        "output": "assets/icons",
        "scan": ["templates", "app"],
        "include": ["mdi:loading"],
        "exclude": ["mdi:test-*"]
      }
    }
  }
}

Option	Default	Description
enabled	true	Enable/disable automatic icon syncing on composer install/update
output	"assets/icons"	Directory for local SVG files (relative to project root)
scan	["templates"]	Directories to scan for meta_icon() calls
include	[]	Icons to always fetch (even if not found in templates)
exclude	[]	Glob patterns for icons to ignore (supports * wildcard)

How it works

1. On composer install or composer update, the plugin scans the configured directories for meta_icon() calls
2. It extracts icon references (e.g. mdi:home, heroicons:chevron-down)
3. Missing icons are fetched in batches from the Iconify API
4. SVGs are saved locally as {output}/{prefix}/{name}.svg
5. At runtime, meta_icon() reads from local files first, with a fallback to iconify/json if installed

Development mode

When Twig debug mode is enabled, icons that are not yet available locally are automatically fetched from the Iconify API on-the-fly and saved for future requests. This means you don't need to run composer ui:icons every time you add a new icon in a template during development.

This on-the-fly fetching is disabled in production to avoid external HTTP requests and latency at runtime. Make sure to run composer ui:icons before deploying.

Backward compatibility

If you prefer the previous approach using the full iconify/json package, you can still install it alongside the plugin:

composer require iconify/json iconify/json-tools

The meta_icon() function will automatically use iconify/json as a fallback when a local SVG file is not found.

Configure the Twig extension from the studiometa/ui package in your project:

• Directly with Twig:

  use StudioMeta\Ui\Extension;
  
  // Get the Twig\Enviromnent instance used by your project
  $twig = get_project_twig_environment();
  // Get the Twig\FilesystemLoader instance used by your project
  $loader = get_project_twig_filesystem_loader();
  
  // Instantiate the extension
  $extension = new Extension(
    $loader,
    'path/to/project/templates',
    'path/to/project/svgs'
  );
  
  // Add the extension
  $twig->addExtension($extension);

• Or via services in a Symfony project:

  # config/services.yaml
  services:
    # add more service definitions when explicit configuration is needed
    # please note that last definitions always *replace* previous ones
    studiometa.ui_extension:
      class: Studiometa\Ui\Extension
      public: false
      arguments:
        - '@twig.loader'
        - '%kernel.project_dir%/templates'
        - '%kernel.project_dir%/public/assets/svg'
      tags:
        - { name: twig.extension }

The Twig extension installs the studiometa/twig-toolkit extension and registers the @ui, @ui-pkg, @svg and @svg-pkg namespaces. The project-aware namespaces resolve your templates or SVGs before falling back to the package; the -pkg namespaces resolve package files directly.

See Templates and customization for namespace lookup, project overrides and safe template extension.