djc-heroicons

HeroIcons.com icons for django-components.

pip install djc-heroicons

Overview

djc-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.

Usage in Python

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",
        },
    },
)

Installation

1. Install the package:

   pip install djc-heroicons
   

2. Add the package to INSTALLED_APPS of your Django project:

   INSTALLED_APPS = [
       ...
       "django_components",
       "djc_heroicons",
       ...
   ]
   

Settings

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,
)

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,
)

component_name

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" / %}

API reference

Icon / {% component "icon" %}

The Icon component accepts following kwargs:

name

str - required

The icon name from HeroIcons.com, e.g. arrow-left-circle.

variant

"outline" | "solid" = "outline"

The icon variant - "outline" or "solid". Defaults to "outline".

size

int = 24

The icon size in pixels. Defaults to 24.

color

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.

stroke_width

float = 1.5

The icon stroke width. Applies only to the "outline" variant. Defaults to 1.5.

viewbox

str = "0 0 24 24"

The icon SVG's viewbox. Defaults to "0 0 24 24".

attrs

Dict | None = None

Optional dictionary to pass HTML attributes to the icon's SVG element.

HeroIconsSettings

NamedTuple for adding intellisense and type hinting to the settings. See Settings.

IconName

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!
]

VariantName

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!
]

Release notes

Read the Release Notes to see the latest features and fixes.

Icons

Outline

academic-cap

adjustments-horizontal

adjustments-vertical

archive-box-arrow-down

archive-box-x-mark

archive-box

arrow-down-circle

arrow-down-left

arrow-down-on-square-stack

arrow-down-on-square

arrow-down-right

arrow-down-tray

arrow-down

arrow-left-circle

arrow-left-end-on-rectangle

arrow-left-start-on-rectangle

arrow-left

arrow-long-down

arrow-long-left

arrow-long-right

arrow-long-up

arrow-path-rounded-square

arrow-path

arrow-right-circle

arrow-right-end-on-rectangle

arrow-right-start-on-rectangle

arrow-right

arrow-top-right-on-square

arrow-trending-down

arrow-trending-up

arrow-turn-down-left

arrow-turn-down-right

arrow-turn-left-down

arrow-turn-left-up

arrow-turn-right-down

arrow-turn-right-up

arrow-turn-up-left

arrow-turn-up-right

arrow-up-circle

arrow-up-left

arrow-up-on-square-stack

arrow-up-on-square

arrow-up-right

arrow-up-tray

arrow-up

arrow-uturn-down

arrow-uturn-left

arrow-uturn-right

arrow-uturn-up

arrows-pointing-in

arrows-pointing-out

arrows-right-left

arrows-up-down

at-symbol

backspace

backward

banknotes

bars-2

bars-3-bottom-left

bars-3-bottom-right

bars-3-center-left

bars-3

bars-4

bars-arrow-down

bars-arrow-up

battery-0

battery-100

battery-50

beaker

bell-alert

bell-slash

bell-snooze

bell

bold

bolt-slash

bolt

book-open

bookmark-slash

bookmark-square

bookmark

briefcase

bug-ant

building-library

building-office-2

building-office

building-storefront

cake

calculator

calendar-date-range

calendar-days

calendar

camera

chart-bar-square

chart-bar

chart-pie

chat-bubble-bottom-center-text

chat-bubble-bottom-center

chat-bubble-left-ellipsis

chat-bubble-left-right

chat-bubble-left

chat-bubble-oval-left-ellipsis

chat-bubble-oval-left

check-badge

check-circle

check

chevron-double-down

chevron-double-left

chevron-double-right

chevron-double-up

chevron-down

chevron-left

chevron-right

chevron-up-down

chevron-up

circle-stack

clipboard-document-check

clipboard-document-list

clipboard-document

clipboard

clock

cloud-arrow-down

cloud-arrow-up

cloud

code-bracket-square

code-bracket

cog-6-tooth

cog-8-tooth

cog

command-line

computer-desktop

cpu-chip

credit-card

cube-transparent

cube

currency-bangladeshi

currency-dollar

currency-euro

currency-pound

currency-rupee

currency-yen

cursor-arrow-rays

cursor-arrow-ripple

device-phone-mobile

device-tablet

divide

document-arrow-down

document-arrow-up

document-chart-bar

document-check

document-currency-bangladeshi

document-currency-dollar

document-currency-euro

document-currency-pound

document-currency-rupee

document-currency-yen

document-duplicate

document-magnifying-glass

document-minus

document-plus

document-text

document

ellipsis-horizontal-circle

ellipsis-horizontal

ellipsis-vertical

envelope-open

envelope

equals

exclamation-circle

exclamation-triangle

eye-dropper

eye-slash

eye

face-frown

face-smile

film

finger-print

fire

flag

folder-arrow-down

folder-minus

folder-open

folder-plus

folder

forward

funnel

gif

gift-top

gift

globe-alt

globe-americas

globe-asia-australia

globe-europe-africa

h1

h2

h3

hand-raised

hand-thumb-down

hand-thumb-up

hashtag

heart

home-modern

home

identification

inbox-arrow-down

inbox-stack

inbox

information-circle

italic

key

language

lifebuoy

light-bulb

link-slash

link

list-bullet

lock-closed

lock-open

magnifying-glass-circle

magnifying-glass-minus

magnifying-glass-plus

magnifying-glass

map-pin

map

megaphone

microphone

minus-circle

minus

moon

musical-note

newspaper

no-symbol

numbered-list

paint-brush

paper-airplane

paper-clip

pause-circle

pause

pencil-square

pencil

percent-badge

phone-arrow-down-left

phone-arrow-up-right

phone-x-mark

phone

photo

play-circle

play-pause

play

plus-circle

plus

power

presentation-chart-bar

presentation-chart-line

printer

puzzle-piece

qr-code

question-mark-circle

queue-list

radio

receipt-percent

receipt-refund

rectangle-group

rectangle-stack

rocket-launch

rss

scale

scissors

server-stack

server

share

shield-check

shield-exclamation

shopping-bag

shopping-cart

signal-slash

signal

slash

sparkles

speaker-wave

speaker-x-mark

square-2-stack

square-3-stack-3d

squares-2x2

squares-plus

star

stop-circle

stop

strikethrough

sun

swatch

table-cells

tag

ticket

trash

trophy

truck

tv

underline

user-circle

user-group

user-minus

user-plus

user

users

variable

video-camera-slash

video-camera

view-columns

viewfinder-circle

wallet

wifi

window

wrench-screwdriver

wrench

x-circle

x-mark

Solid

academic-cap

adjustments-horizontal

adjustments-vertical

archive-box-arrow-down

archive-box-x-mark

archive-box

arrow-down-circle

arrow-down-left

arrow-down-on-square-stack

arrow-down-on-square

arrow-down-right

arrow-down-tray

arrow-down

arrow-left-circle

arrow-left-end-on-rectangle

arrow-left-start-on-rectangle

arrow-left

arrow-long-down

arrow-long-left

arrow-long-right

arrow-long-up

arrow-path-rounded-square

arrow-path

arrow-right-circle

arrow-right-end-on-rectangle

arrow-right-start-on-rectangle

arrow-right

arrow-top-right-on-square

arrow-trending-down

arrow-trending-up

arrow-turn-down-left

arrow-turn-down-right

arrow-turn-left-down

arrow-turn-left-up

arrow-turn-right-down

arrow-turn-right-up

arrow-turn-up-left

arrow-turn-up-right

arrow-up-circle

arrow-up-left

arrow-up-on-square-stack

arrow-up-on-square

arrow-up-right

arrow-up-tray

arrow-up

arrow-uturn-down

arrow-uturn-left

arrow-uturn-right

arrow-uturn-up

arrows-pointing-in

arrows-pointing-out

arrows-right-left

arrows-up-down

at-symbol

backspace

backward

banknotes

bars-2

bars-3-bottom-left

bars-3-bottom-right

bars-3-center-left

bars-3

bars-4

bars-arrow-down

bars-arrow-up

battery-0

battery-100

battery-50

beaker

bell-alert

bell-slash

bell-snooze

bell

bold

bolt-slash

bolt

book-open

bookmark-slash

bookmark-square

bookmark

briefcase

bug-ant

building-library

building-office-2

building-office

building-storefront

cake

calculator

calendar-date-range

calendar-days

calendar

camera

chart-bar-square

chart-bar

chart-pie

chat-bubble-bottom-center-text

chat-bubble-bottom-center

chat-bubble-left-ellipsis

chat-bubble-left-right

chat-bubble-left

chat-bubble-oval-left-ellipsis

chat-bubble-oval-left

check-badge

check-circle

check

chevron-double-down

chevron-double-left

chevron-double-right

chevron-double-up

chevron-down

chevron-left

chevron-right

chevron-up-down

chevron-up

circle-stack

clipboard-document-check

clipboard-document-list

clipboard-document

clipboard

clock

cloud-arrow-down

cloud-arrow-up

cloud

code-bracket-square

code-bracket

cog-6-tooth

cog-8-tooth

cog

command-line

computer-desktop

cpu-chip

credit-card

cube-transparent

cube

currency-bangladeshi

currency-dollar

currency-euro

currency-pound

currency-rupee

currency-yen

cursor-arrow-rays

cursor-arrow-ripple

device-phone-mobile

device-tablet

divide

document-arrow-down

document-arrow-up

document-chart-bar

document-check

document-currency-bangladeshi

document-currency-dollar

document-currency-euro

document-currency-pound

document-currency-rupee

document-currency-yen

document-duplicate

document-magnifying-glass

document-minus

document-plus

document-text

document

ellipsis-horizontal-circle

ellipsis-horizontal

ellipsis-vertical

envelope-open

envelope

equals

exclamation-circle

exclamation-triangle

eye-dropper

eye-slash

eye

face-frown

face-smile

film

finger-print

fire

flag

folder-arrow-down

folder-minus

folder-open

folder-plus

folder

forward

funnel

gif

gift-top

gift

globe-alt

globe-americas

globe-asia-australia

globe-europe-africa

h1

h2

h3

hand-raised

hand-thumb-down

hand-thumb-up

hashtag

heart

home-modern

home

identification

inbox-arrow-down

inbox-stack

inbox

information-circle

italic

key

language

lifebuoy

light-bulb

link-slash

link

list-bullet

lock-closed

lock-open

magnifying-glass-circle

magnifying-glass-minus

magnifying-glass-plus

magnifying-glass

map-pin

map

megaphone

microphone

minus-circle

minus

moon

musical-note

newspaper

no-symbol

numbered-list

paint-brush

paper-airplane

paper-clip

pause-circle

pause

pencil-square

pencil

percent-badge

phone-arrow-down-left

phone-arrow-up-right

phone-x-mark

phone

photo

play-circle

play-pause

play

plus-circle

plus

power

presentation-chart-bar

presentation-chart-line

printer

puzzle-piece

qr-code

question-mark-circle

queue-list

radio

receipt-percent

receipt-refund

rectangle-group

rectangle-stack

rocket-launch

rss

scale

scissors

server-stack

server

share

shield-check

shield-exclamation

shopping-bag

shopping-cart

signal-slash

signal

slash

sparkles

speaker-wave

speaker-x-mark

square-2-stack

square-3-stack-3d

squares-2x2

squares-plus

star

stop-circle

stop

strikethrough

sun

swatch

table-cells

tag

ticket

trash

trophy

truck

tv

underline

user-circle

user-group

user-minus

user-plus

user

users

variable

video-camera-slash

video-camera

view-columns

viewfinder-circle

wallet

wifi

window

wrench-screwdriver

wrench

x-circle

x-mark

Development

Tests

To run tests, use:

tox

Updating icons

To download the icons from HeroIcons.com, run:

python scripts/download_icons.py

This 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