# chirp-ui

URL: /docs/guides/chirp-ui/
Section: guides
Tags: guides, chirp-ui, components, kida, htmx

--------------------------------------------------------------------------------

Overview chirp-ui is a component library for Chirp. It provides Kida template macros — cards, modals, forms, layouts — that render as HTML. Use them with htmx for swaps, SSE for streaming, and View Transitions for polish. Zero JavaScript 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 native HTML (&lt;dialog&gt;, &lt;details&gt;). No client-side framework. Composable — &#123;% slot %&#125; for content injection. Components nest freely. Modern CSS — :has(), container queries, fluid typography, prefers-color-scheme dark mode. Installation Requires Python 3.14+. chirp extra standalone pip install bengal-chirp[ui] # or uv add &quot;bengal-chirp[ui]&quot; pip install chirp-ui # or uv add chirp-ui Setup Two steps to wire chirp-ui into your app: 1. Wire chirp-ui into your app Use Chirp's integration helper to serve chirpui.css, themes, transitions, and register required filters: from chirp import App, AppConfig, use_chirp_ui app = App(AppConfig(template_dir=&quot;templates&quot;)) use_chirp_ui(app) Import: use_chirp_ui is provided by Chirp. Use from chirp import use_chirp_ui when the chirp[ui] extra is installed. If that fails (e.g. older Chirp), use from chirp.ext.chirp_ui import use_chirp_ui. use_chirp_ui(app) adds StaticFiles middleware for the chirp-ui package directory (default /static) and registers filters (bem, field_errors, html_attrs, validate_variant) so chirp-ui components render correctly. 2. Include CSS in your base template &lt;link rel=&quot;stylesheet&quot; href=&quot;/static/chirpui.css&quot;&gt; For View Transitions support, add: &lt;link rel=&quot;stylesheet&quot; href=&quot;/static/chirpui-transitions.css&quot;&gt; Auto-detection When chirp-ui is installed, Chirp's template loader adds the chirp-ui package automatically. No configuration needed for &#123;% from &quot;chirpui/...&quot; %&#125; imports. Templates resolve chirpui/layout.html, chirpui/card.html, etc. from the package. Quick example &#123;% from &quot;chirpui/layout.html&quot; import container, grid, block %&#125; &#123;% from &quot;chirpui/card.html&quot; import card %&#125; &#123;% call container() %&#125; &#123;% call grid(cols=2) %&#125; &#123;% call block() %&#125;&#123;% call card(title=&quot;Hello&quot;) %&#125;&lt;p&gt;Card one.&lt;/p&gt;&#123;% end %&#125;&#123;% end %&#125; &#123;% call block() %&#125;&#123;% call card(title=&quot;World&quot;) %&#125;&lt;p&gt;Card two.&lt;/p&gt;&#123;% end %&#125;&#123;% end %&#125; &#123;% end %&#125; &#123;% end %&#125; App Shell Quick start: Extend chirpui/app_shell_layout.html and fill the blocks. No manual HTML boilerplate: {# target: body #} &#123;% extends &quot;chirpui/app_shell_layout.html&quot; %&#125; &#123;% block brand %&#125;My App&#123;% end %&#125; &#123;% block sidebar %&#125; &#123;% from &quot;chirpui/sidebar.html&quot; import sidebar, sidebar_link, sidebar_section %&#125; &#123;% call sidebar() %&#125; &#123;% call sidebar_section(&quot;Main&quot;) %&#125; {{ sidebar_link(&quot;/&quot;, &quot;Home&quot;) }} {{ sidebar_link(&quot;/items&quot;, &quot;Items&quot;) }} &#123;% end %&#125; &#123;% end %&#125; &#123;% end %&#125; Adding an inner shell: For nested layouts (e.g. forum &gt; subforum), use the shell_section macro from Chirp: &#123;% from &quot;chirp/macros/shell.html&quot; import shell_section %&#125; &#123;% call shell_section(&quot;forum-content&quot;) %&#125; &#123;% block content %&#125;&#123;% end %&#125; &#123;% end %&#125; Migrating from boost.html: Replace &#123;% extends &quot;chirp/layouts/boost.html&quot; %&#125; with &#123;% extends &quot;chirpui/app_shell_layout.html&quot; %&#125;. Add &#123;% block brand %&#125;, &#123;% block sidebar %&#125;, etc. The hx-select=&quot;#page-content&quot; and id=&quot;page-content&quot; are already in place. Page spacing contract: Let the page-level wrapper own vertical rhythm. A good pattern is a parent layout with a page_root block that contains container() + stack(gap=&quot;lg&quot;), while inner blocks such as page_content hold the page-specific sections. Pair that with Page(..., &quot;page_content&quot;, page_block_name=&quot;page_root&quot;, ...) or PageComposition(..., fragment_block=&quot;page_content&quot;, page_block=&quot;page_root&quot;, ...) so boosted navigation swaps the full page shell instead of a too-narrow inner fragment. Manual shell: For full control, chirp-ui provides components for building persistent dashboard shells: sidebar, breadcrumbs, and command_palette. Combine them in a standalone _layout.html: {# target: main #} &lt;!DOCTYPE html&gt; &lt;html lang=&quot;en&quot;&gt; &lt;head&gt; &lt;meta charset=&quot;utf-8&quot;&gt; &lt;title&gt;My Dashboard&lt;/title&gt; &lt;script src=&quot;https://unpkg.com/htmx.org@2.0.4&quot;&gt;&lt;/script&gt; &lt;link rel=&quot;stylesheet&quot; href=&quot;/static/chirpui.css&quot;&gt; &lt;/head&gt; &lt;body&gt; &#123;% from &quot;chirpui/sidebar.html&quot; import sidebar, sidebar_section, sidebar_link %&#125; &#123;% from &quot;chirpui/breadcrumbs.html&quot; import breadcrumbs %&#125; &#123;% from &quot;chirpui/command_palette.html&quot; import command_palette, command_palette_trigger %&#125; &#123;% from &quot;chirpui/toast.html&quot; import toast_container %&#125; &#123;% set cp = current_path | default(&quot;/&quot;) %&#125; &lt;div class=&quot;chirpui-app-shell&quot;&gt; &lt;header class=&quot;chirpui-app-shell__topbar&quot;&gt; &lt;a href=&quot;/&quot; class=&quot;chirpui-app-shell__brand&quot;&gt;My App&lt;/a&gt; &lt;div class=&quot;chirpui-app-shell__topbar-center&quot;&gt; {{ breadcrumbs(breadcrumb_items | default([{&quot;label&quot;: &quot;Home&quot;, &quot;href&quot;: &quot;/&quot;}])) }} &lt;/div&gt; &lt;div class=&quot;chirpui-app-shell__topbar-end&quot;&gt; {{ command_palette_trigger() }} &lt;/div&gt; &lt;/header&gt; &lt;aside class=&quot;chirpui-app-shell__sidebar&quot;&gt; &#123;% call sidebar() %&#125; &#123;% call sidebar_section(&quot;Navigate&quot;) %&#125; {{ sidebar_link(&quot;/&quot;, &quot;Home&quot;, active=cp == &quot;/&quot;) }} {{ sidebar_link(&quot;/items&quot;, &quot;Items&quot;, active=cp.startswith(&quot;/items&quot;)) }} &#123;% end %&#125; &#123;% end %&#125; &lt;/aside&gt; &lt;main id=&quot;main&quot; class=&quot;chirpui-app-shell__main&quot; hx-boost=&quot;true&quot; hx-target=&quot;#main&quot; hx-swap=&quot;innerHTML transition:true&quot; hx-select=&quot;#page-content&quot;&gt; &lt;div id=&quot;page-content&quot;&gt; &#123;% block content %&#125;&#123;% end %&#125; &lt;/div&gt; &lt;/main&gt; &lt;/div&gt; {{ command_palette(search_url=&quot;/search&quot;) }} {{ toast_container() }} &lt;/body&gt; &lt;/html&gt; Why standalone? Chirp's render_with_blocks({&quot;content&quot;: ...}) replaces &#123;% block content %&#125; entirely. If you extend boost.html and put the shell inside &#123;% block content %&#125;, it gets overwritten. A standalone layout puts the shell outside the content block so it always renders. See Filesystem Routing for the full explanation. Why hx-select? On htmx-boosted navigation, Chirp returns a full HTML page (it renders the matched layout). Without hx-select, htmx would swap the entire response into #main, replacing the shell. hx-select=&quot;#page-content&quot; tells htmx to parse the response and extract only #page-content — the shell stays untouched. Why no hx-disinherit? Boosted links inside the content area need to inherit hx-target=&quot;#main&quot;, hx-swap, and hx-select from the &lt;main&gt; element. If you add hx-disinherit, boosted links fall back to targeting body, which replaces everything. Fragment requests with explicit hx-target (e.g. hx-target=&quot;#compare-result&quot;) override the inherited value naturally. Component categories Category Examples Layout container, grid, stack, block, page_header, section_header, divider, breadcrumbs, navbar, sidebar, hero, surface, callout UI card, card_header, modal, drawer, tabs, accordion, dropdown, popover, toast, table, pagination, alert, button_group Forms text_field, password_field, textarea_field, select_field, checkbox_field, toggle_field, radio_field, file_field, date_field, csrf_hidden, form_actions, login_form, signup_form Data display badge, spinner, skeleton, progress, description_list, timeline, tree_view, calendar Streaming streaming_block, copy_btn, model_card — for htmx SSE and LLM UIs See the chirp-ui repository for the full component reference and API. Data layout patterns For dashboard and settings pages, use these patterns for consistent structure: Section with header actions — Put section-level buttons (Refresh, Auto-detect, Run validation) in the section actions slot, not beneath the content: &#123;% from &quot;chirpui/layout.html&quot; import section %&#125; &#123;% from &quot;chirpui/button.html&quot; import btn %&#125; &#123;% call section(&quot;Setup targets&quot;, subtitle=&quot;Configure your IDE&quot;) %&#125; &#123;% slot actions %&#125;{{ btn(&quot;Refresh&quot;, attrs_map={&quot;hx-get&quot;: &quot;/status&quot;, &quot;hx-target&quot;: &quot;#targets&quot;}) }}&#123;% end %&#125; &lt;div id=&quot;targets&quot;&gt;...&lt;/div&gt; &#123;% end %&#125; Settings rows — For label + status + value (e.g. setup targets, health checks), use settings_row_list and settings_row: &#123;% from &quot;chirpui/settings_row.html&quot; import settings_row_list, settings_row %&#125; &#123;% call settings_row_list() %&#125; {{ settings_row(&quot;Cursor IDE&quot;, status=&quot;Configured&quot;, detail=&quot;dori setup cursor&quot;) }} {{ settings_row(&quot;Skills directory&quot;, status=&quot;ok&quot;, detail=&quot;/path/to/skills&quot;) }} &#123;% end %&#125; When to use what — Use description_list for term + detail only (no status badge). Use settings_row_list when you have label + status + detail. Theming chirp-ui uses prefers-color-scheme for dark mode. Override any --chirpui-* variable: :root { --chirpui-accent: #7c3aed; --chirpui-container-max: 80rem; } For manual light/dark toggle, set data-theme=&quot;light&quot; or data-theme=&quot;dark&quot; on &lt;html&gt;. Optional theme: &lt;link rel=&quot;stylesheet&quot; href=&quot;/static/themes/holy-light.css&quot;&gt; chirp new When chirp-ui is installed, chirp new &lt;name&gt; scaffolds a project with use_chirp_ui(app) wired in the app module. The base template includes chirpui.css. Next steps chirp-ui on GitHub — Full component reference, showcase app, and development docs RAG Demo — Uses chirp-ui for layout, cards, badges, and alert Islands Contract — chirp-ui provides island_root and state primitives for high-state widgets

--------------------------------------------------------------------------------

Metadata:
- Word Count: 1121
- Reading Time: 6 minutes