franciscobmacedo / lucide

Use lucide icons in your Django and Jinja templates

lucide

Use lucide icons in your Django and Jinja templates.

Requirements

Python 3.8 to 3.12 supported.

Django 3.2 to 5.0 supported.

Usage

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

Django templates

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

2. Add to your INSTALLED_APPS:

   INSTALLED_APPS = [
       ...,
       "lucide",
       ...,
   ]

3. Now your templates can load the template library with:

       {% load lucide %}

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

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

The library provides one tag (lucide) to render SVG icons which can take these arguments:

• name, positional: the name of the icon to use. You can see the icon names on the lucide 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. It can also 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 lucide grid, there is no default class.

Examples

An "a-arrow-down” icon:

    {% lucide "a-arrow-down" %}

The same icon at 40x40 pixels, and a CSS class:

    {% lucide "a-arrow-down" size=40 class="mr-4" %}

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

    {% lucide "a-arrow-down" stroke_width=1 data_controller="language" %}

Jinja templates

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

2. Adjust your Jinja Environment to add the global lucide function from lucide.jinja. For example:

       from lucide.jinja import lucide
       from jinja2 import Environment
   
       env = Environment()
       env.globals.update({
               "lucide": lucide
           }
       )

3. Now in your templates you can call that function, which will render the corresponding <svg> icons. The function takes these arguments:

• name, positional: the name of the icon to use. You can see the icon names on the lucide 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. 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 lucide grid, there is no default class.

Examples

An "a-arrow-down” icon:

    {{ lucide("a-arrow-down") }}

The same icon at 40x40 pixels and a CSS class:

    {{ lucide("a-arrow-down", size=40, class="mr-4") }}

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

    {{ lucide("a-arrow-down", stroke_width=1, data_controller="language") }}

Acknowledgements

This package is heavely inspired by Adam Johnson's heroicons. It's actually mostly copied from it so a huge thanks Adam!

lucide's Issues

Add Adam Johnson's copyright attribution

Python Version

No response

Django Version

No response

Package Version

No response

Description

Thanks for creating this library. I was actually about to do the same thing by forking @adamchainz's heroicons repo and swapping out the Heroicon specific bits with Lucide, so I'm glad to see someone beat me to the punch.

However, I did notice Adam's copyright notice is nowhere in this repo. I know you shout him out at the bottom of the README, but given that the original package is MIT and that one of the stipulations of that license is copyright attribution, I believe this library should carry his copyright.

Rename library to `django-lucide`

Description

Proposal of renaming lucide to django-lucide :)