django-justmyresource

Use JustMyResource resource packs in your Django and Jinja templates.

Requirements

Python 3.10+ supported.

Django 4.2+ supported (for Django integration).

Jinja2 3.0+ supported (for Jinja integration).

Installation

Install with the appropriate extras:

# For Django templates
pip install django-justmyresource[django]

# For Jinja templates
pip install django-justmyresource[jinja]

# For both
pip install django-justmyresource[django,jinja]

You'll also need to install resource packs. For example, to use Lucide icons:

pip install justmyresource-lucide

Usage

Django Templates

1. Add to your INSTALLED_APPS:

INSTALLED_APPS = [
    ...,
    "django_justmyresource",
    ...,
]

2. Load the template library in your templates:

{% load justmyresource %}

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

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

3. Use the icon tag to render SVG icons:

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

The icon tag accepts these arguments:

• name, positional: The resource name with optional prefix (e.g., "lucide:home" or "justmyresource-lucide/lucide:home").
• size, keyword: An integer for width and height attributes. Defaults to 24. Can be None to preserve original size.
• Any number of keyword arguments: These are added as HTML attributes. Underscores are replaced with dashes (e.g., data_test becomes data-test).

Most attributes are added to the <svg> tag, but these are applied to <path> elements:

• stroke-linecap
• stroke-linejoin
• vector-effect

Examples

Basic icon:

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

Custom size and CSS class:

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

With data attributes and path-level attributes:

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

Jinja Templates

1. Add the icon function to your Jinja environment:

from django_justmyresource.jinja import icon
from jinja2 import Environment

env = Environment()
env.globals.update({
    "icon": icon,
})

2. Use the icon function in your templates:

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

The function accepts the same arguments as the Django template tag:

• name, positional: The resource name with optional prefix.
• size, keyword: Size for width and height. Defaults to 24. Can be None.
• Any number of keyword arguments: HTML attributes (underscores become dashes).

Examples

Basic icon:

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

Custom size and CSS class:

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

With data attributes:

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

Configuration

You can configure the JustMyResource registry via Django settings:

JUSTMYRESOURCE_DEFAULT_PREFIX

Set a default prefix for bare resource names (without a colon):

JUSTMYRESOURCE_DEFAULT_PREFIX = "lucide"

Then you can use bare names in templates:

{% icon "home" %}  # Resolves to "lucide:home"

JUSTMYRESOURCE_BLOCKLIST

Exclude specific resource packs from discovery:

# As a list
JUSTMYRESOURCE_BLOCKLIST = ["pack1", "pack2"]

# Or as a comma-separated string
JUSTMYRESOURCE_BLOCKLIST = "pack1,pack2"

JUSTMYRESOURCE_PREFIX_MAP

Map custom aliases to qualified pack names:

# As a dict
JUSTMYRESOURCE_PREFIX_MAP = {
    "icons": "justmyresource-lucide/lucide",
    "fa": "justmyresource-font-awesome/font-awesome",
}

# Or as a comma-separated string
JUSTMYRESOURCE_PREFIX_MAP = "icons=justmyresource-lucide/lucide,fa=justmyresource-font-awesome/font-awesome"

Resource Name Resolution

Resource names can be specified in multiple formats:

• Qualified name: "justmyresource-lucide/lucide:home" - Always unique, no ambiguity
• Short pack name: "lucide:home" - Works if the pack name is unique
• Alias: "luc:home" - If the pack defines aliases via get_prefixes()
• Bare name: "home" - Requires JUSTMYRESOURCE_DEFAULT_PREFIX to be set

See the JustMyResource documentation for more details on resource resolution.

Available Resource Packs

Check the JustMyResource Icons repository for available icon packs:

• justmyresource-lucide - Lucide icons
• justmyresource-heroicons - Heroicons
• justmyresource-phosphor - Phosphor icons
• justmyresource-font-awesome - Font Awesome
• justmyresource-material-icons - Material Icons
• justmyresource-mdi - Material Design Icons

Acknowledgements

This project was initially inspired by lucide, a Django/Jinja integration for Lucide icons. The lucide project itself is heavily inspired by Adam Johnson's heroicons, and much of the template tag implementation and SVG rendering logic follows similar patterns.

Special thanks to:

• Francisco Macedo for the lucide project, which served as the initial reference
• Adam Johnson for the heroicons project, which established the pattern for Django icon template tags

License

MIT