Use Lucide icons in your Twig templates

[alinnert]

Note: I've also posted this in the Lucide repository, so this tutorial includes a general instruction how to use Lucide icons in any PHP or Twig project, but it also points out things specific to Craft CMS. It also might work with other icon sets as well.

---

Here's how to use Lucide icons in a PHP (and potentially Twig) project.

In a nutshell

• Install npm-asset/lucide-static via Asset Packagist
• Read the content of the individual icon file from vendor/npm-asset/lucide-static/icons/{icon-name}.svg
• Change icon settings with CSS if necessary

Install dependencies

Setup Asset Packagist

To install packages from Asset Packagist add the following to your composer.json:

{
  // Rest of your `composer.json`...
  "repositories": [
    {
      "type": "composer",
      "url": "https://asset-packagist.org"
    }
  ]
}

Install lucide-static package

Now you can run

composer require npm-asset/lucide-static

Using Lucide in PHP

The PHP function

/**
 * Returns the SVG of an icon.
 */
function lucide(string $name): string
{
  $iconPathSegments = [
    VENDOR_DIR,
    'npm-asset',
    'lucide-static',
    'icons',
    "{$name}.svg",
  ];
  $iconPath = implode(DIRECTORY_SEPARATOR, $iconPathSegments);
  if (!file_exists($iconPath)) {
    throw new Exception("Lucide icon '{$name}' not found.");
  }
  $icon = file_get_contents($iconPath);
  if ($icon === false) {
    throw new Exception("Error reading Lucide icon '{$name}'.");
  }
  return $icon;
}

Replace VENDOR_DIR with the actual path to your vendor directory. If you use a PHP framework or CMS you might have different ways to get that path. For Craft CMS you can use Craft::getAlias('@vendor').

If it better suits your use-case instead of throwing an exception you can also return a default icon or something else if the requested icon doesn't exist.

Now you can use the function like following. It returns the file content of the SVG file (e.g. <svg>...</svg>).

lucide('arrow-right');

Using Lucide in Twig

Creating the Twig extension

You can register the function above (with a few changes) as a Twig function like this:

class MyExtension extends \Twig\Extension\AbstractExtension
{
  public function getFunctions()
  {
    return [
      new \Twig\TwigFunction('lucide', $this->lucide(...)),
    ];
  }

  public function lucide(string $name): \Twig\Markup
  {
    $iconPathSegments = [
      VENDOR_DIR,
      'npm-asset',
      'lucide-static',
      'icons',
      "{$name}.svg",
    ];
    $iconPath = implode(DIRECTORY_SEPARATOR, $iconPathSegments);
    if (!file_exists($iconPath)) {
      throw new Exception("Lucide icon '{$name}' not found.");
    }
    $icon = file_get_contents($iconPath);
    if ($icon === false) {
      throw new Exception("Error reading Lucide icon '{$name}'.");
    }
    return new \Twig\Markup($icon, 'UTF-8');
  }
}

Notice that the function now returns a \Twig\Markup instead of a string. This prevents Twig from escaping the SVG code.

Use AsTwigFunction attribute instead of getFunctions

Optionally, you can also use the AsTwigFunction attribute (available since Twig 3.21) like below and skip the getFunctions function but as of this writing Craft CMS ships with Twig 3.15 which doesn't support this attribute yet.

class MyExtension extends \Twig\Extension\AbstractExtension
{
  #[AsTwigFunction('lucide')]
  public function lucide(string $name): \Twig\Markup
  {
    // Same code as above.
  }
}

Register Twig function

Then you can register this extension in your Twig environment like this:

$twig = new \Twig\Environment($loader);
$twig->addExtension(new MyExtension());

This might work differently depending on what framework or CMS you're using. For instance, in a Craft CMS module you register your extension like this:

if (Craft::$app->request->getIsSiteRequest()) {
  Craft::$app->view->registerTwigExtension(new MyExtension());
}

Now you can use this function in Twig like this:

{{ lucide('arrow-right') }}

Change options

Now you can change settings like color, size, and stroke-width using CSS:

svg {
  color: red;
  width: 48px;
  height: 48px;
  stroke-width: 1px;
}