fasthtml-lucide

Lucide SVG icons for FastHTML. Icons are bundled in the Python package: no Node.js, JavaScript, CDN or static-file setup is needed in your application.

Installation

Install with uv:

uv add fasthtml-lucide

Or with pip:

pip install fasthtml-lucide

Usage

from fasthtml.common import Button
from fasthtml_lucide import Icon

Button(Icon("sun", cls="size-5 text-yellow-500"), "Light mode")

Icon(name, *, cls="", size=24) accepts kebab-case Lucide names and returns an inline SVG. Colors inherit through currentColor. Original SVG classes are kept. Invalid or unknown names raise ValueError.

Icon("settings", size=20)
Icon("heart", cls="text-red-500")

Icons are decorative (aria-hidden="true"), so icon-only buttons should have an accessible label on the button itself.

Typed icon names

The package generates an IconName type containing every available icon name, providing editor autocomplete and type checking for misspelled names.

You can also use the type in your own components:

from fasthtml.common import Button
from fasthtml_lucide import Icon, IconName


def IconButton(icon: IconName, label: str):
    return Button(Icon(icon), label)

Automatic updates

The library is automatically updated to the latest stable lucide-static release on npm, with checks running daily. The PyPI version matches the npm version; Python-only fixes may add a .postN suffix.

For Tailwind CSS integration with persistent watch mode, see fasthtml-tailwindcss.

Development

Build

Requires Python 3.11+, uv and Node.js/npm when building from Git:

uv build

The build hook downloads the matching lucide-static release and bundles its SVGs and license in both the wheel and sdist. Building from the sdist does not require Node.js/npm.

To run the tests against the built package:

uv venv
uv pip install --group test dist/*.whl
uv run --no-project python -m pytest tests
uv run --no-project python scripts/check_dist.py

Automated releases

The Release workflow checks npm daily and can also be run manually. It updates the package version, builds and tests the release, creates a Git tag and publishes to PyPI using Trusted Publishing.

Manual releases

For a Python-only fix, increment the post-release version (for example, 1.61.0 → 1.61.0.post1 → 1.61.0.post2):

uv version --bump post --frozen

Commit your fix and pyproject.toml, push to the default branch, then select Actions → Release → Run workflow on GitHub. The workflow creates the tag and publishes to PyPI. The Lucide version stays the same unless a newer npm release is available.

Links

• GitHub repository
• PyPI package

License

The Python wrapper is MIT licensed. Bundled Lucide icons retain the upstream ISC license and the MIT notices for icons derived from Feather, included in fasthtml_lucide/LUCIDE-LICENSE.