Metadata-Version: 2.4
Name: tablericons2
Version: 1.0.0
Summary: Use Tabler Icons in your Django and Jinja templates.
Author-email: Francisco Macedo <me@fmacedo.com>, Julian Wachholz <jw@continis.ch>
License: MIT
Project-URL: Changelog, https://github.com/continis/tablericons/blob/main/CHANGELOG.md
Project-URL: Repository, https://github.com/continis/tablericons
Keywords: Django
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django :: 6.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: django
Requires-Dist: django>=5.2; extra == "django"
Provides-Extra: jinja
Requires-Dist: jinja2>=2.8; extra == "jinja"
Dynamic: license-file

# tablericons

<a href="https://github.com/continis/tablericons/actions?workflow=CI">
    <img
        src="https://img.shields.io/github/actions/workflow/status/continis/tablericons/main.yml.svg?branch=main&style=for-the-badge"
        alt="CI"
        style="max-width: 100%;"
    >
</a>
<a href="https://pypi.org/project/tablericons/">
    <img
        src="https://img.shields.io/pypi/v/tablericons.svg?style=for-the-badge"
        alt="pypi"
        style="max-width: 100%;"
    >
</a>
<a href="https://github.com/psf/black">
    <img
        src="https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge"
        alt="black"
        style="max-width: 100%;"
    >
</a>
<a href="https://github.com/pre-commit/pre-commit">
    <img
        src="https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge"
        alt="pre-commit"
        style="max-width: 100%;"
    >
</a>


Use [Tabler Icons](https://tabler.io/icons/) in your Django and Jinja templates.

## Requirements

Python from 3.10 supported.

Django from 5.2 supported.

## Usage

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

### Django templates

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

2.  Add to your `INSTALLED_APPS`:

    ```python
    INSTALLED_APPS = [
        ...,
        "tablericons",
        ...,
    ]
    ```

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

    ```django
        {% load tablericons %}
    ```

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

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

The library provides one tag (`icon`) 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 [tabler grid](https://tabler.io/icons/).

- `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 [tabler grid](https://tabler.io/icons/), there is no default `class`.

#### Examples

An "a-arrow-down” icon:

```django
    {% icon "a-arrow-down" %}
```

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

```django
    {% icon "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:

```django
    {% icon "a-arrow-down" stroke_width=1 data_controller="language" %}
```

### Jinja templates

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

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

   ```python
       from tablericons.jinja import tablericons
       from jinja2 import Environment

       env = Environment()
       env.globals.update({
               "tablericons": tablericons
           }
       )
    ```
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 [tabler grid](https://tabler.io/icons/)

- `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 [tabler grid](https://tabler.io/icons/), there is no default `class`.

#### Examples

An "a-arrow-down” icon:

```jinja
    {{ icon("a-arrow-down") }}
```

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

```jinja
    {{ icon("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:

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

## Acknowledgements

This package is forked from [franciscobmacedo/lucide](https://github.com/franciscobmacedo/lucide) which in turn is heavely inspired by [Adam Johnson's heroicons](https://github.com/adamchainz/heroicons).
