heroicons

Use heroicons in your Django and Jinja templates.

Requirements

Python 3.7 to 3.10 supported.

Django 2.2 to 4.0 supported.

---

Working on a Django project? Improve your skills with one of my books.

---

Usage

The heroicons package supports both Django templates and Jinja templates. Follow the appropriate guide below.

Django templates

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

2. Add to your INSTALLED_APPS:

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

Now in your templates you can load the template library with:

{% load heroicons %}

This provides two tags to render SVG icons: heroicon_outline and heroicon_solid, corresponding to the two icon styles in the set. The tags 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 20 for solid.

• 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
  • stroke-width
  • vector-effect

Examples

An outline “academic-cap” icon:

{% heroicon_outline "academic-cap" %}

The same icon, solid, at 40x40 pixels, with some CSS classes:

{% heroicon_outline "academic-cap" size=40 class="h-4 w-4 inline" %}

That icon again, but with the paths changed to a narrower stroke width, and a "data-controller" attribute declared:

{% 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 two global functions heroicon_outline and heroicon_solid, imported from heroicons.jinja. For example:

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

Now in your templates you can call those two functions, which render <svg> icons corresponding to the two 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 20 for solid.

• 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
  • stroke-width
  • vector-effect

Examples

An outline “academic-cap” icon:

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

The same icon, solid, at 40x40 pixels, with some CSS classes:

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

That icon again, but with the paths changed to a narrower stroke width, and a "data-controller" attribute declared:

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