heroicons 2.5.0

Django templates

1. Install with python -m pip install heroicons[django].

2. Add to your INSTALLED_APPS:

   INSTALLED_APPS = [
       ...,
       "heroicons",
       ...,
   ]

Now your templates can load the template library with:

{% load heroicons %}

Alternatively, make the library available in all templates by adding it to the builtins option:

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        # ...
        "OPTIONS": {
            # ...
            "builtins": [
                ...,
                "heroicons.templatetags.heroicons",
                ...,
            ],
        },
    }
]

The library provides three tags to render SVG icons: heroicon_outline, heroicon_solid, and heroicon_mini. These tags correspond to the three styles in the icon set and take these arguments:

• name, positional: the name of the icon to use. You can see the icon names on the heroicons.com grid.

• size, keyword: an integer that will be used for the width and height attributes of the output <svg> tag. Defaults to the icons’ designed sizes: 24 for outline and solid, and 20 for mini. Can be None, in which case no width or height attributes will be output.

• Any number of keyword arguments. These will be added as attributes in the output HTML. Underscores in attribute names will be replaced with dashes, allowing you to define e.g. data- attributes.

  Most attributes will be added to the <svg> tag containing the icon, but these attributes will be attached to the inner <path> tags instead:

  • stroke-linecap

  • stroke-linejoin

  • vector-effect

Note: unlike the SVG code you can copy from heroicons.com, there is no default class.

{% heroicon_outline "academic-cap" %}

{% heroicon_outline "academic-cap" size=40 class="mr-4" %}

{% heroicon_outline "academic-cap" stroke_width=1 data_controller="academia" %}

Jinja templates

1. Install with python -m pip install heroicons[jinja].

2. Adjust your Jinja Environment to add the three global functions heroicon_outline, heroicon_solid and heroicon_mini, imported from heroicons.jinja. For example:

   from heroicons.jinja import heroicon_outline, heroicon_solid, heroicon_mini
   from jinja2 import Environment
   
   env = Environment()
   env.globals.update(
       {
           "heroicon_outline": heroicon_outline,
           "heroicon_solid": heroicon_solid,
           "heroicon_mini": heroicon_mini,
       }
   )

Now in your templates you can call those functions, which render <svg> icons corresponding to the icon styles in the set. The functions take these arguments:

• name, positional: the name of the icon to use. You can see the icon names on the heroicons.com grid.

• size, keyword: an integer that will be used for the width and height attributes of the output <svg> tag. Defaults to the icons’ designed sizes: 24 for outline and solid, and 20 for mini. Can be None, in which case no width or height attributes will be output.

• Any number of keyword arguments. These will be added as HTML attributes to the output HTML. Underscores in attribute names will be replaced with dashes, allowing you to define e.g. data- attributes.

  Most attributes will be added to the <svg> tag containing the icon, but these attributes will be attached to the inner <path> tags instead:

  • stroke-linecap

  • stroke-linejoin

  • vector-effect

Note: unlike the SVG code you can copy from heroicons.com, there is no default class.

{{ heroicon_outline("academic-cap") }}

{{ heroicon_solid("academic-cap", size=40, class="mr-4") %}

{{ heroicon_outline("academic-cap", stroke_width=1, data_controller="academia") %}