| Name | heroicons JSON |
| Version |
2.9.0
JSON |
| download |
| home_page | None |
| Summary | Use heroicons in your Django and Jinja templates. |
| upload_time | 2024-10-28 11:54:28 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
django
jinja
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
=========
heroicons
=========
.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/heroicons/main.yml.svg?branch=main&style=for-the-badge
:target: https://github.com/adamchainz/heroicons/actions?workflow=CI
.. image:: https://img.shields.io/badge/Coverage-100%25-success?style=for-the-badge
:target: https://github.com/adamchainz/heroicons/actions?workflow=CI
.. image:: https://img.shields.io/pypi/v/heroicons.svg?style=for-the-badge
:target: https://pypi.org/project/heroicons/
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge
:target: https://github.com/psf/black
.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge
:target: https://github.com/pre-commit/pre-commit
:alt: pre-commit
Use `heroicons <https://heroicons.com/>`__ in your Django and Jinja templates.
----
**Improve your Django and Git skills** with `my books <https://adamj.eu/books/>`__.
----
Requirements
------------
Python 3.9 to 3.13 supported.
Django 4.2 to 5.1 supported.
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``:
.. code-block:: python
INSTALLED_APPS = [
...,
"heroicons",
...,
]
Now your templates can load the template library with:
.. code-block:: django
{% load heroicons %}
Alternatively, make the library available in all templates by adding it to `the builtins option <https://docs.djangoproject.com/en/stable/topics/templates/#django.template.backends.django.DjangoTemplates>`__:
.. code-block:: python
TEMPLATES = [
{
"BACKEND": "django.template.backends.django.DjangoTemplates",
# ...
"OPTIONS": {
# ...
"builtins": [
...,
"heroicons.templatetags.heroicons",
...,
],
},
}
]
The library provides these tags to render SVG icons in their corresponding styles:
* ``heroicon_micro``
* ``heroicon_mini``
* ``heroicon_outline``
* ``heroicon_solid``
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 <https://heroicons.com/>`__.
* ``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 solid, ``20`` for mini, and ``16`` for micro.
Can 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 `heroicons.com <https://heroicons.com/>`__, there is no default ``class``.
Examples
^^^^^^^^
An outline “academic-cap” icon:
.. code-block:: django
{% heroicon_outline "academic-cap" %}
The same icon, solid, at 40x40 pixels, and a CSS class:
.. code-block:: django
{% heroicon_outline "academic-cap" size=40 class="mr-4" %}
That icon again, but with the paths changed to a narrower stroke width, and a "data-controller" attribute declared:
.. code-block:: django
{% 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 global ``heroicon_*`` functions from ``heroicons.jinja``.
For example:
.. code-block:: python
from heroicons.jinja import (
heroicon_micro,
heroicon_mini,
heroicon_outline,
heroicon_solid,
)
from jinja2 import Environment
env = Environment()
env.globals.update(
{
"heroicon_micro": heroicon_micro,
"heroicon_mini": heroicon_mini,
"heroicon_outline": heroicon_outline,
"heroicon_solid": heroicon_solid,
}
)
Now in your templates you can call those functions, which render ``<svg>`` icons corresponding to the 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 <https://heroicons.com/>`__.
* ``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 solid, ``20`` for mini, and ``16`` for micro.
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 `heroicons.com <https://heroicons.com/>`__, there is no default ``class``.
Examples
^^^^^^^^
An outline “academic-cap” icon:
.. code-block:: jinja
{{ heroicon_outline("academic-cap") }}
The same icon, solid, at 40x40 pixels, and a CSS class:
.. code-block:: jinja
{{ heroicon_solid("academic-cap", size=40, class="mr-4") %}
That icon again, but with the paths changed to a narrower stroke width, and a "data-controller" attribute declared:
.. code-block:: jinja
{{ heroicon_outline("academic-cap", stroke_width=1, data_controller="academia") %}
CLI
---
Many icons were renamed in version 2 of heroicons.
To assist you with migrating from version 1, this package includes a CLI that can update your heroicons template tags.
Invoke the CLI like so:
.. code-block:: console
$ python -m heroicons update <filename> <filename2> ...
To run it on all your template files, you can use |git ls-files pipe xargs|__:
.. |git ls-files pipe xargs| replace:: ``git ls-files | xargs``
__ https://adamj.eu/tech/2022/03/09/how-to-run-a-command-on-many-files-in-your-git-repository/
.. code-block:: console
$ git ls-files -- '*.html' | xargs python -m heroicons update
The tool will update icon names for those that were renamed in v2, as per the table in the `heroicons release notes <https://github.com/tailwindlabs/heroicons/releases/tag/v2.0.0>`__.
It should find both Django and Jinja template tags:
.. code-block:: diff
-{% heroicon_outline "archive" class="mr-2" %}
+{% heroicon_outline "archive-box" class="mr-2" %}
-{{ heroicon_solid("archive", class="mr-2") }}
+{{ heroicon_solid("archive-box", class="mr-2") }}
Also note that ``solid`` icons changed their default size from 20px to 24px.
If you are using them without specifying a size, they will now be larger, which could break some designs.
You can keep the v1 size by specifying it exactly:
.. code-block:: django
{% heroicon_solid "archive-box" size=20 %}
.. code-block:: jinja
{{ heroicon_solid("archive-box", size=20) }}
Or through other mechanisms:
* Tailwind’s `width <https://tailwindcss.com/docs/width>`__ and `height <https://tailwindcss.com/docs/height>`__ classes: ``w-5 h-5``
* other CSS classes
* sizing the containing elements
Due to the variety of ways to size icons, it’s unfortunately not possible to automatically add the size to unsized solid icons.
Good luck, and may the odds be ever in your favour.
Raw data
{
"_id": null,
"home_page": null,
"name": "heroicons",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "Django Jinja",
"author": null,
"author_email": "Adam Johnson <me@adamj.eu>",
"download_url": "https://files.pythonhosted.org/packages/33/b9/1115b843da2a1ddf6cf01f1403e96d756bc2621872f6f7926b917975b64d/heroicons-2.9.0.tar.gz",
"platform": null,
"description": "=========\nheroicons\n=========\n\n.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/heroicons/main.yml.svg?branch=main&style=for-the-badge\n :target: https://github.com/adamchainz/heroicons/actions?workflow=CI\n\n.. image:: https://img.shields.io/badge/Coverage-100%25-success?style=for-the-badge\n :target: https://github.com/adamchainz/heroicons/actions?workflow=CI\n\n.. image:: https://img.shields.io/pypi/v/heroicons.svg?style=for-the-badge\n :target: https://pypi.org/project/heroicons/\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge\n :target: https://github.com/psf/black\n\n.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge\n :target: https://github.com/pre-commit/pre-commit\n :alt: pre-commit\n\nUse `heroicons <https://heroicons.com/>`__ in your Django and Jinja templates.\n\n----\n\n**Improve your Django and Git skills** with `my books <https://adamj.eu/books/>`__.\n\n----\n\nRequirements\n------------\n\nPython 3.9 to 3.13 supported.\n\nDjango 4.2 to 5.1 supported.\n\nUsage\n-----\n\nThe ``heroicons`` package supports both Django templates and Jinja templates.\nFollow the appropriate guide below.\n\nDjango templates\n~~~~~~~~~~~~~~~~\n\n1. Install with ``python -m pip install heroicons[django]``.\n\n2. Add to your ``INSTALLED_APPS``:\n\n .. code-block:: python\n\n INSTALLED_APPS = [\n ...,\n \"heroicons\",\n ...,\n ]\n\nNow your templates can load the template library with:\n\n.. code-block:: django\n\n {% load heroicons %}\n\nAlternatively, make the library available in all templates by adding it to `the builtins option <https://docs.djangoproject.com/en/stable/topics/templates/#django.template.backends.django.DjangoTemplates>`__:\n\n.. code-block:: python\n\n TEMPLATES = [\n {\n \"BACKEND\": \"django.template.backends.django.DjangoTemplates\",\n # ...\n \"OPTIONS\": {\n # ...\n \"builtins\": [\n ...,\n \"heroicons.templatetags.heroicons\",\n ...,\n ],\n },\n }\n ]\n\nThe library provides these tags to render SVG icons in their corresponding styles:\n\n* ``heroicon_micro``\n* ``heroicon_mini``\n* ``heroicon_outline``\n* ``heroicon_solid``\n\nThe tags take these arguments:\n\n* ``name``, positional: the name of the icon to use.\n You can see the icon names on the `heroicons.com grid <https://heroicons.com/>`__.\n\n* ``size``, keyword: an integer that will be used for the width and height attributes of the output ``<svg>`` tag.\n Defaults to the icons\u2019 designed sizes: ``24`` for outline and solid, ``20`` for mini, and ``16`` for micro.\n Can be ``None``, in which case no width or height attributes will be output.\n\n* Any number of keyword arguments.\n These will be added as attributes in the output HTML.\n Underscores in attribute names will be replaced with dashes, allowing you to define e.g. ``data-`` attributes.\n\n Most attributes will be added to the ``<svg>`` tag containing the icon, but these attributes will be attached to the inner ``<path>`` tags instead:\n\n * ``stroke-linecap``\n * ``stroke-linejoin``\n * ``vector-effect``\n\nNote: unlike the SVG code you can copy from `heroicons.com <https://heroicons.com/>`__, there is no default ``class``.\n\nExamples\n^^^^^^^^\n\nAn outline \u201cacademic-cap\u201d icon:\n\n.. code-block:: django\n\n {% heroicon_outline \"academic-cap\" %}\n\nThe same icon, solid, at 40x40 pixels, and a CSS class:\n\n.. code-block:: django\n\n {% heroicon_outline \"academic-cap\" size=40 class=\"mr-4\" %}\n\nThat icon again, but with the paths changed to a narrower stroke width, and a \"data-controller\" attribute declared:\n\n.. code-block:: django\n\n {% heroicon_outline \"academic-cap\" stroke_width=1 data_controller=\"academia\" %}\n\nJinja templates\n~~~~~~~~~~~~~~~\n\n1. Install with ``python -m pip install heroicons[jinja]``.\n\n2. Adjust your Jinja ``Environment`` to add the global ``heroicon_*`` functions from ``heroicons.jinja``.\n For example:\n\n .. code-block:: python\n\n from heroicons.jinja import (\n heroicon_micro,\n heroicon_mini,\n heroicon_outline,\n heroicon_solid,\n )\n from jinja2 import Environment\n\n env = Environment()\n env.globals.update(\n {\n \"heroicon_micro\": heroicon_micro,\n \"heroicon_mini\": heroicon_mini,\n \"heroicon_outline\": heroicon_outline,\n \"heroicon_solid\": heroicon_solid,\n }\n )\n\nNow in your templates you can call those functions, which render ``<svg>`` icons corresponding to the icon styles in the set.\nThe functions take these arguments:\n\n* ``name``, positional: the name of the icon to use.\n You can see the icon names on the `heroicons.com grid <https://heroicons.com/>`__.\n\n* ``size``, keyword: an integer that will be used for the width and height attributes of the output ``<svg>`` tag.\n Defaults to the icons\u2019 designed sizes: ``24`` for outline and solid, ``20`` for mini, and ``16`` for micro.\n Can be ``None``, in which case no width or height attributes will be output.\n\n* Any number of keyword arguments.\n These will be added as HTML attributes to the output HTML.\n Underscores in attribute names will be replaced with dashes, allowing you to define e.g. ``data-`` attributes.\n\n Most attributes will be added to the ``<svg>`` tag containing the icon, but these attributes will be attached to the inner ``<path>`` tags instead:\n\n * ``stroke-linecap``\n * ``stroke-linejoin``\n * ``vector-effect``\n\nNote: unlike the SVG code you can copy from `heroicons.com <https://heroicons.com/>`__, there is no default ``class``.\n\nExamples\n^^^^^^^^\n\nAn outline \u201cacademic-cap\u201d icon:\n\n.. code-block:: jinja\n\n {{ heroicon_outline(\"academic-cap\") }}\n\nThe same icon, solid, at 40x40 pixels, and a CSS class:\n\n.. code-block:: jinja\n\n {{ heroicon_solid(\"academic-cap\", size=40, class=\"mr-4\") %}\n\nThat icon again, but with the paths changed to a narrower stroke width, and a \"data-controller\" attribute declared:\n\n.. code-block:: jinja\n\n {{ heroicon_outline(\"academic-cap\", stroke_width=1, data_controller=\"academia\") %}\n\nCLI\n---\n\nMany icons were renamed in version 2 of heroicons.\nTo assist you with migrating from version 1, this package includes a CLI that can update your heroicons template tags.\n\nInvoke the CLI like so:\n\n.. code-block:: console\n\n $ python -m heroicons update <filename> <filename2> ...\n\nTo run it on all your template files, you can use |git ls-files pipe xargs|__:\n\n.. |git ls-files pipe xargs| replace:: ``git ls-files | xargs``\n__ https://adamj.eu/tech/2022/03/09/how-to-run-a-command-on-many-files-in-your-git-repository/\n\n.. code-block:: console\n\n $ git ls-files -- '*.html' | xargs python -m heroicons update\n\nThe tool will update icon names for those that were renamed in v2, as per the table in the `heroicons release notes <https://github.com/tailwindlabs/heroicons/releases/tag/v2.0.0>`__.\nIt should find both Django and Jinja template tags:\n\n.. code-block:: diff\n\n -{% heroicon_outline \"archive\" class=\"mr-2\" %}\n +{% heroicon_outline \"archive-box\" class=\"mr-2\" %}\n\n -{{ heroicon_solid(\"archive\", class=\"mr-2\") }}\n +{{ heroicon_solid(\"archive-box\", class=\"mr-2\") }}\n\nAlso note that ``solid`` icons changed their default size from 20px to 24px.\nIf you are using them without specifying a size, they will now be larger, which could break some designs.\nYou can keep the v1 size by specifying it exactly:\n\n.. code-block:: django\n\n {% heroicon_solid \"archive-box\" size=20 %}\n\n.. code-block:: jinja\n\n {{ heroicon_solid(\"archive-box\", size=20) }}\n\nOr through other mechanisms:\n\n* Tailwind\u2019s `width <https://tailwindcss.com/docs/width>`__ and `height <https://tailwindcss.com/docs/height>`__ classes: ``w-5 h-5``\n* other CSS classes\n* sizing the containing elements\n\nDue to the variety of ways to size icons, it\u2019s unfortunately not possible to automatically add the size to unsized solid icons.\n\nGood luck, and may the odds be ever in your favour.\n",
"bugtrack_url": null,
"license": null,
"summary": "Use heroicons in your Django and Jinja templates.",
"version": "2.9.0",
"project_urls": {
"Changelog": "https://github.com/adamchainz/heroicons/blob/main/CHANGELOG.rst",
"Funding": "https://adamj.eu/books/",
"Repository": "https://github.com/adamchainz/heroicons"
},
"split_keywords": [
"django",
"jinja"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a0fdec090ea0a4f7e5aeb1fda250ea04739489be62f20594248d527ba9d48f9a",
"md5": "d075a80c2512840475e78d1dfa99c01a",
"sha256": "c9b380221bc7397aed99fcca86b8e6cd210346bf5326bcd7626cd5df69dce2d3"
},
"downloads": -1,
"filename": "heroicons-2.9.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d075a80c2512840475e78d1dfa99c01a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 414967,
"upload_time": "2024-10-28T11:54:26",
"upload_time_iso_8601": "2024-10-28T11:54:26.053283Z",
"url": "https://files.pythonhosted.org/packages/a0/fd/ec090ea0a4f7e5aeb1fda250ea04739489be62f20594248d527ba9d48f9a/heroicons-2.9.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "33b91115b843da2a1ddf6cf01f1403e96d756bc2621872f6f7926b917975b64d",
"md5": "7e58fdc917766f3aee6d3f835b602f28",
"sha256": "d1b0787e233b6e59583fc1877d77709e21941d2ad0fadb53a27c65a3691d7ebf"
},
"downloads": -1,
"filename": "heroicons-2.9.0.tar.gz",
"has_sig": false,
"md5_digest": "7e58fdc917766f3aee6d3f835b602f28",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 420275,
"upload_time": "2024-10-28T11:54:28",
"upload_time_iso_8601": "2024-10-28T11:54:28.143729Z",
"url": "https://files.pythonhosted.org/packages/33/b9/1115b843da2a1ddf6cf01f1403e96d756bc2621872f6f7926b917975b64d/heroicons-2.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-28 11:54:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "adamchainz",
"github_project": "heroicons",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "heroicons"
}
