eleventy-plugin-heroicons

🛡 Shortcodes to add Heroicons to your Eleventy projects

Get started

Install the package:

npm i -D eleventy-plugin-heroicons

Then add the plugin to your .eleventy.js file:

// .eleventy.js
module.exports = eleventyConfig => {
    eleventyConfig.addPlugin(require('eleventy-plugin-heroicons'));
}

Usage

This plugin adds three shortcodes: heroicon, heroicon_outline, and heroicon_solid.

Note: These examples use Liquid template syntax, which is the default for Eleventy. If you are using another template engine like Nunjucks, the syntax might be slightly different.

heroicon

Args: style: ("outline"|"solid"), name: string, alt?: string, attributes?: object|string

{% heroicon "outline" "archive" %}
{% heroicon "solid" "x" "Close menu" %}
{% heroicon "solid" "x" "Close menu" "width=25 x-data='{ open: false }'" %}

If you are using a templating language that supports object arguments like Nunjucks, then you can replace the attributes string with an object:

<!-- Nunjucks -->
{% heroicon "solid", "x", "Close menu", { width: 25, "x-data": "{ open: false }" } %}

heroicon_outline/heroicon_solid

⚠️ Warning: These APIs are subject to change in future releases.

These wrap the heroicon shortcode and pass a style.

Args: name: string, alt?: string, attributes?: object|string

{% heroicon_outline "archive" %}
{% heroicon_solid "archive" %}

{% heroicon_outline "x" "Close menu" %}
{% heroicon_solid "archive" %}
{% heroicon_solid "archive" undefined "height=25" %}

Configuration

eleventy-plugin-heroicons offers a few options on a configuration object passed to Eleventy's addPlugin():

• className?: string Adds a class to all heroicons
• errorOnMissing: boolean (default: false) Throw an error when passed an invalid style/name or invalid attribute

Pass the configuration object when adding the plugin:

// .eleventy.js
module.exports = eleventyConfig => {
    eleventyConfig.addPlugin(require('eleventy-plugin-heroicons'), {
        className: 'icon',
        errorOnMissing: true
    });
}

Styling

The svg element receives two data attributes that you can use for styling:

• data-heroicon-name="string"
• data-heroicon-style="(outline|solid)"

You could add the following to your stylesheets:

/* Solid icons */
[data-heroicon-style="solid"] {
    width: 20px;
}

/* Arrow down icon */
[data-heroicon-name="arrow-down"] {
    color: darkgreen;
}

/* All icons */
[data-heroicon-name] {
    padding: 2ch;
}

If you passed a className to the configuration object, then you could use that to select all icons.

License

MIT © Sean McPherson