An optional, opinionated UI layer for Chirp — gorgeous by default, htmx-native.

pip install chirp chirp-ui

{% from "chirpui/layout.html" import container, grid, block %}
{% from "chirpui/card.html" import card %}

{% call container() %}
    {% call grid(cols=2) %}
        {% call block() %}{% call card(title="Hello") %}<p>Card one.</p>{% end %}{% end %}
        {% call block() %}{% call card(title="World") %}<p>Card two.</p>{% end %}{% end %}
    {% end %}
{% end %}

chirp-ui is an optional companion design system for Chirp. It provides Kida template macros — cards, modals, forms, layouts — that render as HTML. It is one polished, opinionated way to build Chirp apps, not the framework itself and not the only way to use Chirp. Use it with htmx for swaps, SSE for streaming, and View Transitions for polish. No client-side framework required for layout.

What's good about it:

• Gorgeous by default — Full visual design out of the box. Override --chirpui-* CSS variables to customize.
• htmx-native — Interactive components use htmx or Alpine.js. Dropdown, modal, tray, tabs, theme toggle, copy button use Alpine for declarative behavior.
• Composable — {% slot %} for content injection. Components nest freely.
• Modern CSS — :has(), container queries, fluid typography, prefers-color-scheme dark mode.

# pip
pip install chirp-ui

# uv
uv add chirp-ui

Requires Python 3.14+. When used with Chirp, components are auto-detected — no configuration needed.

You do not need chirp-ui to use Chirp. Use it when you want the companion component library, default design language, and app-shell patterns.

Version compatibility:

What's stable: Core macros (layout, card, modal, forms, alert, badge), filters (bem, html_attrs, validate_variant, validate_size), VARIANT_REGISTRY/SIZE_REGISTRY, static path, get_loader, register_filters. See SECURITY.md for | safe usage.

What may change: New component variants/sizes, API surface of __all__-excluded internals, Alpine.js migration patterns.

Serve assets:

from chirp.middleware.static import StaticFiles
import chirp_ui

app.add_middleware(StaticFiles(
    directory=str(chirp_ui.static_path()),
    prefix="/static"
))

pip install chirp chirp-ui
python examples/component-showcase/app.py

:root {
    --chirpui-accent: #7c3aed;
    --chirpui-container-max: 80rem;
    /* Optional: tune shade ratios for all colors */
    --chirpui-shade-hover: 85%;
    --chirpui-shade-muted: 15%;
}

from kida import ChoiceLoader, Environment, FileSystemLoader
from chirp_ui import get_loader

env = Environment(
    loader=ChoiceLoader([
        FileSystemLoader("templates"),
        get_loader(),
    ])
)

{% from "chirpui/islands.html" import island_root %}

{% call island_root("editor", props={"doc_id": doc.id}, mount_id="editor-root") %}
<p>Fallback editor UI (SSR) if JavaScript is unavailable.</p>
{% end %}

from chirp import App, AppConfig

app = App(AppConfig(islands=True, islands_contract_strict=True))

{% from "chirpui/state_primitives.html" import grid_state, wizard_state, upload_state %}

{% call grid_state("team_grid", ["name", "role"], mount_id="grid-root") %}
...
{% end %}

{% from "chirpui/fragment_island.html" import poll_trigger %}

<div id="collections-results"></div>
{{ poll_trigger("/collections/status?refresh=1", "#collections-results", delay="1s") }}

document.addEventListener('chirpui:dropdown-selected', (e) => {
  if (e.detail.action) htmx.ajax('POST', '/api/action', { values: { action: e.detail.action } });
});

{% from "chirpui/alert.html" import alert %}
{% from "chirpui/card.html" import card %}
{% from "chirpui/button.html" import btn %}
{% from "chirpui/callout.html" import callout %}

{% call alert(variant="warning", icon="⚠", title="Heads up") %}Body text{% end %}
{% call card(title="Feature", subtitle="Optional subtitle", icon="◆") %}Content{% end %}
{{ btn("Save", icon="✓") }}
{% call callout(icon="💡", title="Tip") %}Use Unicode for icons.{% end %}

{% from "chirpui/card.html" import card %}
{% call card(title="Settings", icon="⚙") %}
{% slot header_actions %}
<button class="chirpui-btn chirpui-btn--ghost">⋯</button>
{% end %}
<p>Body content.</p>
{% end %}

• HTML over the wire. Components render as blocks for htmx swaps, SSE streams, and View Transitions. The server is the source of truth.
• Companion, not core. chirp-ui is an optional layer on top of Chirp, not a requirement for using the framework.
• CSS as the design language. Modern features (:has(), aspect-ratio, clamp()) used where they add value. All animations respect prefers-reduced-motion.
• Composable. {% slot %} for content injection. Components nest freely. No wrapper classes.
• Minimal dependency. kida-templates only. Chirp optional for auto-registration.

• Python >= 3.14
• kida-templates >= 0.2.6

Interactive components (dropdown, modal, tray, tabs, theme toggle, copy button) require Alpine.js 3.x. The chirpui/app_shell_layout.html and chirpui/app_layout.html layouts include Alpine via CDN. For custom layouts, add Alpine before using these components.

git clone https://github.com/lbliii/chirp-ui.git
cd chirp-ui
uv sync --group dev
pytest

A structured reactive stack written in pure Python for 3.14t free-threading. Chirp is the framework; chirp-ui is one optional UI layer built on top of it.

Python-native. Free-threading ready. No npm required.

MIT