HeroIcons.com icons for django-components.
pip install djc-heroiconsdjc-heroicons adds an Icon component that renders an <svg> element with the icons from HeroIcons.com. This icon is accessible in Django templates as {% component "icon" %}.
Use the name kwarg to specify the icon name:
<div>
Items:
<ul>
<li>
{% component "icon" name="academic-cap" / %}
</li>
</ul>
</div>By default the component renders the "outline" variant. To render the "solid" variant of the icon, set kwarg variant to "solid":
{% component "icon" name="academic-cap" variant="solid" / %}Common changes like color, size, or stroke width can all be set directly on the component:
{% component "icon"
name="academic-cap"
size=48
color="red"
stroke_width=1.2
/ %}If you need to pass attributes to the <svg> element, you can use the attrs kwarg, which accepts a dictionary:
{% component "icon"
name="academic-cap"
attrs:id="my-svg"
attrs:class="p-4 mb-3"
attrs:data-id="test-123"
/ %}See all available input for Icon component in API reference.
All of the above is possible also from within Python, by importing Icon:
from djc_heroicons import Icon
content = Icon.render(
kwargs={
"name": "academic-cap",
"variant": "solid",
"size": 48,
"attrs": {
"id": "my-svg",
"class": "p-4 mb-3",
},
},
)-
Install the package:
pip install djc-heroicons
-
Add the package to
INSTALLED_APPSof your Django project:INSTALLED_APPS = [ ... "django_components", "djc_heroicons", ... ]
You can configure the behavior of the djc-heroicons library
by setting a DJC_HEROICONS variable in your Django settings file.
DJC_HEROICONS can be either a plain dictionary, or a instance of HeroIconSettings. The latter helps with intellisense and type hints:
DJC_HEROICONS = {
"registry": custom_registry,
}
# or
from djc_heroicons import HeroIconsSettings
DJC_HEROICONS = HeroIconsSettings(
registry=custom_registry,
)ComponentRegistry | str | None = None
The django-components' ComponentRegistry to which the icon component should be registered.
If None, the icon is registered into the default registry.
custom_registry = ComponentRegistry()
DJC_HEROICONS = HeroIconsSettings(
registry=custom_registry,
)str | None = "icon"
The name under which the Icon component will be available from within Django templates.
If None, the component is registered with the name "icon".
{% component "icon" name="academic-cap" / %}Example:
If you set this to "heroicons":
DJC_HEROICONS = HeroIconsSettings(
component_name="heroicons",
)You will use the component like this:
{% component "heroicons" name="academic-cap" / %}The Icon component accepts following kwargs:
str - required
The icon name from HeroIcons.com, e.g. arrow-left-circle.
"outline" | "solid" = "outline"
The icon variant - "outline" or "solid". Defaults to "outline".
int = 24
The icon size in pixels. Defaults to 24.
str = "currentColor"
The icon color. Defaults to "currentColor".
- If the icon is
"outline", this sets the stroke color. - If the icon is
"solid", this sets the fill color.
float = 1.5
The icon stroke width. Applies only to the "outline" variant. Defaults to 1.5.
str = "0 0 24 24"
The icon SVG's viewbox. Defaults to "0 0 24 24".
Dict | None = None
Optional dictionary to pass HTML attributes to the icon's SVG element.
NamedTuple for adding intellisense and type hinting to the settings. See Settings.
Type alias that holds all the valid icon names, e.g.
Literal["arrow-left-circle", "arrow-down", ...]
Use this for type validation and intellisense.
Example:
In the example below, the "icon" key of menu is typed, so Mypy or other linters pick it up as an error:
from typing import List, TypedDict
from djc_heroicons import IconName
class MenuItem(TypedDict):
name: str
icon: IconName
menu: List[MenuItem]: = [
{"name": "Home", "icon": "home"},
{"name": "Settings", "icon": "cog-6-tooth"},
{"name": "Account", "icon": "user-circe"}, <-- Typo!
]Type alias that holds all the valid icon variants, e.g.
Literal["outline", "solid"]
Use this for type validation and intellisense.
Example:
In the example below, the "variant" key of menu is typed, so Mypy or other linters pick it up as an error:
from typing import List, TypedDict
from djc_heroicons import IconName, VariantName
class MenuItem(TypedDict):
name: str
icon_variant: VariantName
icon: IconName
menu: List[MenuItem]: = [
{"name": "Home", "icon_variant": "outline", "icon": "home"},
{"name": "Settings", "icon_variant": "solid", "icon": "cog-6-tooth"},
{"name": "Account", "icon_variant": "outlien", "icon": "user-circe"}, <-- Typos!
]Read the Release Notes to see the latest features and fixes.
To run tests, use:
toxTo download the icons from HeroIcons.com, run:
python scripts/download_icons.pyThis will save them to src/djc_heroicons/icons.py.
Next, to update the list of icons in the README, run:
python scripts/gen_icon_docs.py