` whose first `h1` is the page title, the page body inside `

`, and a ``. An `.eyebrow` in the article names the page's section. ```jinja layouts/docs.html {% extends "layouts/base.html" %} {% from "docs/macros.html" import markdown_actions %} {% set nav = docsNav(url) %} {% block content %}

{% block docs %}{% endblock %}

{% if nav.prev %}{{ nav.prev.title }}{% endif %} {% if nav.next %}{{ nav.next.title }}{% endif %}

{% endblock %} ``` ## Navigation One file lists the docs in order, in sections. It is found through the template roots, like `json()`: ```json data/docs-nav.json { "sections": [ { "title": "Getting started", "items": [ { "title": "Introduction", "href": "/docs" }, { "title": "Installation", "href": "/docs/installation", "description": "Set it up." } ] } ] } ``` `docsNav(url)` returns where a page sits in it: | Field | Description | | --- | --- | | `sections` | The file's sections, for the sidebar. | | `pages` | Every entry, in order. | | `current` | The page's own entry, or null when it is not listed. | | `active` | href of the closest entry: the page's own, or the longest one its URL starts with. /docs/servers/express marks /docs/servers active when it has no entry of its own, so a section can have pages of its own. | | `section` | Title of the active entry's section ("Docs" when none), for the eyebrow. | | `prev, next` | The entries before and after the page's own, or null. | Entries can carry anything else you need (this site marks components with `"component": true` to list them on the components page). Pages missing from the file still get Markdown, and sort with their closest listed parent. ## Heading anchors Every `h2` and `h3` in `[data-docs-content]` gets an `id` from its text and a `#` link, styled by htmx-ui's `.heading-anchor`. An explicit `id` is kept, so give one to a heading whose wording may change while links to it must not. Headings inside links, `.not-prose` component markup, `.demo` previews and `[data-md-skip]` are not sections and are left alone. The HTML, the Markdown and the sitemap all see the same ids. ## What it publishes | URL | Description | | --- | --- | | `.md` | Each docs page as Markdown with frontmatter: /docs.md, /docs/setup.md. Demos become their source, tables Markdown tables, alerts blockquotes. | | `/llms.txt` | llmstxt.org index: every docs page as a Markdown link with its description, grouped by section. | | `/llms-full.txt` | Every docs page's Markdown in one file. | | `/sitemap.json` | Every page with title, description, section, outline and section text. The index site search reads. | | `/docs/sitemap.json` | The same for the docs only. | | `/sitemap.xml` | For search engines. The 404 page is left out of both sitemaps. | | `/robots.txt` | Points crawlers at the sitemap. A robots.txt in public/ is used instead. | `htmx-ui dev` and the [server adapters](https://susonwaiba.github.io/htmx-ui/docs/servers) generate them on request; `htmx-ui build` writes them to `dist/`. Mark purely visual blocks `data-md-skip` to leave them out of the Markdown and the search text. ## Macros ```jinja {% from "docs/macros.html" import demo, classes, markdown_actions %} {% call demo() %}{% endcall %} {{ classes([["btn", "The base class."], ["btn-primary", "The main action."]]) }} {{ markdown_actions(url) }} ``` | Macro | Description | | --- | --- | | `demo(class, source, isolate)` | A live preview of the call body with its source underneath. In Markdown it becomes just the source. | | `classes(rows, heading)` | A two-column reference table of [name, description] rows. | | `markdown_actions(page_url)` | A "Copy Markdown" clipboard button and a "View .md" link for the page. | ## Options | Option | Description | | --- | --- | | `prefix` | Route prefix of the docs. Default "/docs". | | `nav` | The navigation file. Default "data/docs-nav.json"; false for none. | | `name, description` | The site, for llms.txt and sitemap.json. | | `anchors` | Heading ids and # links. Default true. | | `robots` | Publish /robots.txt. Default true. | > **Set the site URL for production builds** Sitemaps and llms.txt carry absolute URLs from `url` in the config, or `$SITE_URL`. The build warns when neither is set. ## For other plugins Its `api` renders and converts pages for plugins that build on it: ```ts const docs = config.plugins.find((p) => p.name === "docs")?.api as DocsApi | undefined; for (const page of docs?.pages() ?? []) console.log(page.url, page.title, page.sections.length); ``` `pages()` renders every page (with `title`, `description`, `section`, `headings` and `sections`), `markdown(page)` converts one, and `isDocs(url)` tells docs pages from the rest. The converters and generators are exported too: `pageMarkdown`, `pageMeta`, `addHeadingAnchors`, `sitemapJson`, `llmsTxt`. --- title: "Versions plugin" description: "htmx-ui-plugin-versions: keep every release's docs online as a frozen build, with a version switcher, an old-version banner and commands to name and archive versions." url: "/docs/plugins/versions" section: "Plugins" --- # Versions plugin htmx-ui-plugin-versions: keep every release's docs online as a frozen build, with a version switcher, an old-version banner and commands to name and archive versions. `htmx-ui-plugin-versions` keeps the docs of every release online. The version being written renders live at `/docs`, as usual. Each older one is a **frozen build** in `archive/v/`, served at `/docs/v/`: its pages, scripts and styles exactly as they were released, so later changes to components or layouts can never break them. This website's [versions](https://susonwaiba.github.io/htmx-ui/docs/versions) work this way. ## Install ```bash bun bun add htmx-ui-plugin-versions ``` ```bash npm npm install htmx-ui-plugin-versions ``` ```bash pnpm pnpm add htmx-ui-plugin-versions ``` ```bash yarn yarn add htmx-ui-plugin-versions ``` ```ts htmx-ui.config.ts import { defineConfig } from "htmx-ui-engine"; import docs from "htmx-ui-plugin-docs"; import versions from "htmx-ui-plugin-versions"; export default defineConfig({ plugins: [docs(), versions()], }); ``` List the versions. The one being written has no number yet; it is `next` until it is released: ```json data/versions.json { "latest": "next", "versions": [{ "id": "next", "label": "next" }] } ``` ```css styles.css @import "tailwindcss"; @import "htmx-ui/styles.css"; @import "htmx-ui-plugin-versions/styles.css"; ``` ```ts app.ts import { initVersions } from "htmx-ui-plugin-versions/client"; document.addEventListener("DOMContentLoaded", () => initVersions()); ``` It works without the docs plugin, but with it each archived version also keeps its Markdown and its own sitemap, the sitemaps list every version, and [search](https://susonwaiba.github.io/htmx-ui/docs/plugins/search) follows the version being read. ## The switcher and the banner ```jinja layouts/docs.html {% from "versions/macros.html" import version_switcher, version_banner %}

``` | Template | Description | | --- | --- | | `version_switcher(class, links)` | A Dropdown listing every version. links are extra entries under a separator: [{ title, href }]. At runtime the client points each version at the same page when it exists there, and adds versions released after the page was built. | | `version_banner()` | Where an archived page's "you're viewing an old version" notice goes, linking to the same page in the latest version. Empty on the latest docs. | | `docsVersions()` | The versions file as templates see it: latest, current, label, manifest and versions (id, label, released, path, latest). | Archiving bakes the banner into every frozen page, so it shows without JavaScript. The client only refreshes it, so an old version learns about releases that came after it. ## Releasing a version The plugin adds two CLI commands. Give them scripts, so they run on the runtime you build with: ```json package.json { "scripts": { "docs:name": "htmx-ui versions:name", "docs:archive": "htmx-ui versions:archive" } } ``` ```bash bun bun run docs:name 1.2.0 bun run docs:archive ``` ```bash npm npm run docs:name 1.2.0 npm run docs:archive ``` ```bash pnpm pnpm run docs:name 1.2.0 pnpm run docs:archive ``` ```bash yarn yarn run docs:name 1.2.0 yarn run docs:archive ``` 1. **`versions:name `** numbers `next` and dates it today. Docs are versioned per minor before 1.0 (`0.2.0` becomes `0.2`) and per major after (`1.2.0` becomes `1`); pass `0.2` or `1` to choose yourself. It refuses when the latest version already has a number. 2. **`versions:archive`** builds the site, freezes the latest version's built docs into `archive/v/` and opens a new `next`. Links between docs pages are rewritten into the snapshot, assets move to `_assets/`, pages get `noindex` so old versions don't compete with the latest in search results, and every `` gets `hx-boost="false"` so nothing on a frozen page boosts the live site's code into it. `--skip-build` archives the `dist/` you already have. Commit `archive/` and `data/versions.json`. > **Never edit the archive by hand** Snapshots are built output. Fix an old version by rebuilding it from its release and archiving it again. Patch releases update the current docs in place rather than getting a version of their own. ## URLs | URL | Description | | --- | --- | | `/docs/...` | The latest version, rendered from pages/docs. | | `/docs/v/...` | An archived version, from archive/v/. Also /docs/v.md and each page's .md with the docs plugin. | | `/docs/versions.json` | The manifest: every version with its path, release date, sitemap and the pages it has. | The version in development never reaches a URL: it is always served at `/docs`, and only archived versions get a `/v` prefix. Links that must point across versions carry `data-version-link`, which archiving leaves alone, and `hx-boost="false"`: every version ships its own theme and scripts, so switching versions must load the target page fresh instead of swapping the body under this version's stylesheet. Archiving applies the same rule to the whole snapshot, by setting `hx-boost="false"` on its ``. A frozen page ships its own theme, stylesheet and scripts, so no link inside it — its logo, footer, sidebar or a link in the prose — may be boosted into the current site, and no current page may be swapped into it: every navigation out of a snapshot is a full page load. ## Options | Option | Description | | --- | --- | | `prefix` | Route prefix of the docs, the same as the docs plugin's. Default "/docs". | | `file` | The versions file, relative to the project root. Default "data/versions.json". | | `archive` | Where frozen versions are kept, relative to the project root. Default "archive". | The functions behind the commands are exported for release scripts of your own: `nameVersion`, `startNext`, `archiveDocs`, `versionId`, `readVersionsFile` and `writeVersionsFile`. This repository's `bun run version:set` uses them to name the docs version and set its package versions in one step. --- title: "Search plugin" description: "htmx-ui-plugin-search: a Ctrl/⌘K command palette that fuzzy-searches every page and section, with no server or search service." url: "/docs/plugins/search" section: "Plugins" --- # Search plugin htmx-ui-plugin-search: a Ctrl/⌘K command palette that fuzzy-searches every page and section, with no server or search service. `htmx-ui-plugin-search` adds a search button and a command palette. It opens with `Ctrl`/`⌘` `K` or `/`, matches pages and the sections inside them as you type, and opens the page or jumps straight to the section. There is no server and no search service: it reads one JSON index, once, the first time it opens (or as soon as the pointer reaches the button). Try it in this site's header. ## Install The index is the `sitemap.json` the [docs plugin](https://susonwaiba.github.io/htmx-ui/docs/plugins/docs) publishes, so install both: ```bash bun bun add htmx-ui-plugin-search htmx-ui-plugin-docs ``` ```bash npm npm install htmx-ui-plugin-search htmx-ui-plugin-docs ``` ```bash pnpm pnpm add htmx-ui-plugin-search htmx-ui-plugin-docs ``` ```bash yarn yarn add htmx-ui-plugin-search htmx-ui-plugin-docs ``` ```ts htmx-ui.config.ts import { defineConfig } from "htmx-ui-engine"; import docs from "htmx-ui-plugin-docs"; import search from "htmx-ui-plugin-search"; export default defineConfig({ plugins: [docs(), search()], }); ``` ```css styles.css @import "tailwindcss"; @import "htmx-ui/styles.css"; @import "htmx-ui-plugin-search/styles.css"; ``` ```ts app.ts import { initSearch } from "htmx-ui-plugin-search/client"; document.addEventListener("DOMContentLoaded", () => initSearch()); ``` Put the button and the palette in your header: ```jinja partials/header.html {% from "search/macros.html" import search %}

... {{ search() }}

``` ## search() | Argument | Description | | --- | --- | | `src` | The index to search. Default "/sitemap.json". | | `label` | The button's text. Default "Search docs…". | | `placeholder` | The input's placeholder. | It renders a wide button with the shortcut on larger screens, an icon button on small ones, and one `

``` ## Collapsed `.breadcrumb-ellipsis` stands in for steps left out of a long path. Make it the trigger of a dropdown that lists them, and give it an `aria-label`. ```html ``` ## Collapsing when it doesn't fit With `data-breadcrumb` on the `

`, the breadcrumb stays on one line and collapses by itself. Add a hidden ellipsis item, and a hidden separator, after the first step. Whenever the breadcrumb changes width, steps in the middle are hidden from the left until it fits, the ellipsis appears, and its menu lists the hidden steps as links. The first step and the current page always stay; the page name truncates as a last resort. Drag the corner of the box to resize it: ```html

``` It works the same in a fragment returned by htmx. To collapse a fixed number of steps instead, whatever the width, write the ellipsis yourself as in [Collapsed](#collapsed), and leave out `data-breadcrumb`. ## Reference | Class | Description | | --- | --- | | `.breadcrumb` | The

: one line, collapsing middle steps into [data-breadcrumb-ellipsis] when it doesn't fit. | | `[data-breadcrumb-ellipsis]` | The hidden ellipsis item; its [role=menu] is filled with the hidden steps. | --- title: "Navigation menu" description: "A site's main navigation: links, and buttons that open panels of links, from simple lists to mega menus." url: "/docs/components/navigation-menu" section: "Components" --- # Navigation menu A site's main navigation: links, and buttons that open panels of links, from simple lists to mega menus. ```html ``` ## Markup - A ` ``` ## Indicator `.navigation-menu-indicator` on the nav adds an arrow pointing from the open trigger to its panel. ```html ``` ## Vertical `.navigation-menu-vertical` stacks the items, for a sidebar or a menu on a small screen. Panels open in place under their trigger and push the items below down; they open by click or keyboard only, never on hover, and grids become a single column. ```html ``` ## Small screens A horizontal menu with wide panels doesn't fit a phone, and there is no hover there. Show it from the `md` breakpoint up, and below that a button that opens the same links in a vertical menu: in a [collapsible](https://susonwaiba.github.io/htmx-ui/docs/components/collapsible) under the header, as here, or in a [sheet](https://susonwaiba.github.io/htmx-ui/docs/components/sheet) from the side. Narrow the window to see the switch. ```html

``` Only one of the two menus is displayed at a time, so screen readers meet one navigation landmark. Render both from the same data (a `json()` file and a loop) so they never drift apart. ## Keyboard | Key | Action | | --- | --- | | `Tab` | Moves through the triggers and links in page order, and into an open panel after its trigger. Leaving an item closes its panel. | | `Enter` `Space` | On a trigger, opens or closes its panel. On a link, follows it (`Enter`). | | `→` `←` | On the top level, moves to the next or previous trigger or link, wrapping round. | | `Home` `End` | Moves to the first or last top-level item; in a panel, to its first or last link. | | `↓` | On a trigger, opens its panel and moves to its first link. In a panel, moves to the next link. | | `↑` | In a panel, moves to the previous link, or from the first link back to the trigger. | | `Esc` | Closes the open panel and returns focus to its trigger. | In a vertical menu, `↓` and `↑` move through the top-level items and the links of an open panel as one list. ## Accessibility - The nav is a navigation landmark: give it an `aria-label`, and a different one to each navigation on the page. - Triggers are buttons with `aria-expanded` and `aria-controls`, so screen readers announce collapsed or expanded. Links stay links, read in order, and there are no menu roles to change how the keyboard works. - A closed panel is hidden with `visibility`, so it is out of the tab order and the accessibility tree, and can fade out as well as in. - Arrow keys are a shortcut on top of `Tab`, which reaches everything. - Hover-opened panels can be dismissed with `Esc` without moving the pointer, and wait for the pointer to cross into them (WCAG 1.4.13). - With reduced motion, panels fade without zooming and the chevron turns without animating. ## With htmx Boost the menu's links with `hx-boost:inherited="true"` on the nav, or on `` as this site does, so following one swaps the page without a full reload. The panel closes when one of its links is followed. If the response replaces the whole body, the server renders the new `aria-current`; if it swaps only the main content (`hx-target` and `hx-select`), also return the menu with `hx-swap-oob` so the current link moves. ```html ``` A panel fires `navigation-menu:open` and `navigation-menu:close` (they bubble) each time it opens and closes. Fill a panel from the server the first time it opens with `hx-trigger="navigation-menu:open once"`: ```html ``` ## Reference | Class / attribute | Description | | --- | --- | | `.navigation-menu` | The

. Add data-navigation-menu and an aria-label. | | `.navigation-menu-list` | The

: a link, or a trigger and its panel. | | `.navigation-menu-trigger` | Button that opens the panel after it. Add aria-expanded="false"; a chevron icon inside turns over while open. | | `.navigation-menu-link` | A link: top-level, styled like a trigger, or in a panel, with a title and description or an icon. aria-current="page" marks the current page. | | `.navigation-menu-content` | A panel, below its trigger at its left edge. | | `.navigation-menu-content-center / -end` | Centre the panel on its trigger, or line it up with the right edge. | | `.navigation-menu-grid` | A

` around a `

` in an `

`, with `aria-label="Page 2"` so it isn't read as a bare number. - The current page has `aria-current="page"`, which outlines it. It stays a link, so it can be reloaded or copied. - Previous and next add `.pagination-previous` / `.pagination-next` (and `rel="prev"` / `rel="next"`), with their text in a `.pagination-label`. - `.pagination-ellipsis` stands in for pages left out. It is `aria-hidden`: the page numbers either side already show the gap. - Plain links work without JavaScript; add htmx attributes to swap only the list (see [With htmx](#htmx)). The [macro](#macro) works out which pages to show and writes all of this for you. ## Page numbers only Leave out previous and next when there are few pages. ```html ``` ## Disabled On the first page there is no previous one. Keep the link in place, so nothing shifts, but drop its `href` and add `aria-disabled="true"`: it fades, can't be clicked and leaves the tab order. A `

Page 2 of 5

``` With htmx, the select can reload the table on change: `hx-get="/invoices" hx-trigger="change" hx-target="#invoices" hx-include="this"`. ## Sizes `.pagination-sm` and `.pagination-lg` on the `

` match `.btn-sm` and `.btn-lg` heights. ```html ``` ## Responsive `.pagination-responsive` fits a phone: below the `sm` breakpoint (640px) only previous, the current page and next show, and the previous / next labels are hidden visually but still read out. Narrow the window to see it. ```html ``` ## Macro `pagination(page, total)` works out which pages to show and writes the whole `

`. `{page}` in `href` becomes each link's page number. ```jinja {% from "components/pagination/pagination.html" import pagination %} {{ pagination(5, 10, href="/invoices?page={page}") }} {{ pagination(2, 5, numbers=false, icons=true, first=true, last=true, size="sm", outline=true) }} ``` ### Which pages are shown The first and last `boundaries` pages always show, and `siblings` pages either side of the current one. An ellipsis stands in for two or more pages left out; a gap of one page shows that page instead. Once there are more pages than fit, the list always has the same number of items (2 × `siblings` + 2 × `boundaries` + 3, so 7 by default), so the links don't move about as the current page changes. | Call | Pages shown | | --- | --- | | `pagination(1, 10)` | [1] 2 3 4 5 … 10 | | `pagination(4, 10)` | 1 2 3 [4] 5 … 10 | | `pagination(5, 10)` | 1 … 4 [5] 6 … 10 | | `pagination(7, 10)` | 1 … 6 [7] 8 9 10 | | `pagination(10, 10)` | 1 … 6 7 8 9 [10] | | `pagination(3, 7)` | 1 2 [3] 4 5 6 7 (all fit) | | `pagination(10, 20, siblings=2, boundaries=2)` | 1 2 … 8 9 [10] 11 12 … 19 20 | | `pagination(10, 20, boundaries=0)` | … 9 [10] 11 … | The first, a middle and the last page of ten, rendered: ```html ``` | Parameter | Description | | --- | --- | | `page, total` | Required. The current page (kept within 1…total) and the number of pages. | | `href="?page={page}"` | Each link's URL; {page} is replaced with its page number. | | `siblings=1` | Pages shown on each side of the current one. | | `boundaries=1` | Pages always shown at each end. | | `numbers=true` | false leaves out the page numbers: previous / next (and first / last) only. | | `previous=true, next=true` | true for "Previous" / "Next", a string for other text, false to leave the link out. | | `first=false, last=false` | true for icon-only links labelled "First page" / "Last page", or a string for another label. | | `icons=false` | true makes previous / next icon-only; their text becomes the aria-label. | | `page_label="Page {page}"` | Each page link's aria-label. | | `responsive=false` | true adds .pagination-responsive. | | `size` | "sm" or "lg". | | `outline=false` | true adds .pagination-outline. | | `label="Pagination"` | The

's aria-label. | | `attrs` | More attributes for every enabled link, as a dict; {page} is replaced in the values. | | `class` | More classes on the

. | ## With htmx Keep the links' `href`s, so the pages work without JavaScript, and let htmx fetch the same URLs and swap only the region holding the table and its pagination. With the macro, `attrs` puts the attributes on every link: ```jinja

…rows for this page…

{{ pagination(page, pages, href="/invoices?page={page}", attrs={ "hx-get": "/invoices?page={page}", "hx-target": "#invoices", "hx-select": "#invoices", "hx-swap": "outerHTML", "hx-push-url": "true" }) }}

``` which writes links like: ```html 3 ``` - `hx-select="#invoices"` picks the region out of the full page the server returns, so one route serves both normal visits and htmx requests. A server that checks the `HX-Request` header can return just the region instead and drop `hx-select`. - The region swapped includes the pagination, so the current page and the disabled ends update with the rows. - `hx-push-url="true"` puts `?page=3` in the address bar, so reloading and the back button land on the same page. - Disabled links have no `href` and the macro leaves their htmx attributes off, so they send nothing. - After the swap, focus is lost with the old link. Move it to the top of the region (for example a heading with `tabindex="-1"`) if keyboard users would otherwise start again from the top of the page. To write the attributes once rather than on every link, put them on the `

` as inherited attributes (`hx-target:inherited="#invoices"` and so on) and use `hx-boost:inherited="true"`, which makes htmx fetch each link's `href`. ## Keyboard | Key | Action | | --- | --- | | `Tab` `Shift`+`Tab` | Move between the links; disabled ones are skipped | | `Enter` | Go to that page | ## Accessibility - The `

` is a navigation landmark; its `aria-label` tells it apart from the site's other navigation. Use different labels when a page has two. - `aria-current="page"` tells screen readers which page is showing; don't rely on the outline alone. - Icon-only links need an `aria-label`. Links with visible text don't: an `aria-label` that differs from the text breaks voice control ("click Next"). - Page links are labelled "Page 3" rather than "3"; pass `page_label` to the macro to translate it. ## Reference | Class | Description | | --- | --- | | `.pagination` | The

: centres the list in its container. | | `.pagination-content` | The

: 32px / 40px links (36px by default). | | `.pagination-outline` | On the

: every link outlined; the current page filled. | | `.pagination-responsive` | On the

: below sm, only previous, the current page and next, with labels visually hidden. | --- title: "Sidebar" description: "A composable, themeable app navigation column: groups, menus, badges, actions and sub-menus, collapsing to an icon rail or off the screen, with an off-canvas panel on mobile." url: "/docs/components/sidebar" section: "Components" --- # Sidebar A composable, themeable app navigation column: groups, menus, badges, actions and sub-menus, collapsing to an icon rail or off the screen, with an off-canvas panel on mobile. ## Preview Switchboard, a made-up console for watching an htmx app's requests: an environment switcher and a route search in the header, a Monitor group with counts, collapsible Ship items with sub-menus, collapsible Saved views with actions, a usage meter and an account menu in the footer, a rail and a trigger. Collapse it with the button, the rail on its edge or `Ctrl` `B` (`⌘` `B` on a Mac) after clicking inside the frame: it shrinks to icons, and each one shows its label as a tooltip. [Open it on its own page](https://susonwaiba.github.io/htmx-ui/examples/sidebar), where it also remembers its state and turns into an off-canvas panel on a narrow window. ## Structure A sidebar is plain markup with classes for each part. The layout holds the sidebar and the main area; the sidebar holds a header, a scrolling content area and a footer; the content holds groups of menus. ```html app.html ``` - `.sidebar-layout` places the sidebar and `.sidebar-inset` (the page's main area) side by side. - `.sidebar` with `data-sidebar` is the column. Options are data attributes on it: [side](#side), [variant](#variant), [collapsible](#collapsible) and [breakpoint](#mobile). - `.sidebar-header` and `.sidebar-footer` stay put; `.sidebar-content` between them scrolls. - `.sidebar-group` is a section of the content, with a `.sidebar-group-label`, an optional `.sidebar-group-action` and its `.sidebar-menu`. - `.sidebar-menu` is a `

`, which takes the remaining width. ```html

…

``` The navigation of these docs is one, set up this way (see [the docs navigation](#docs-navigation)). ## Header and footer Use the header for a logo, a workspace or environment switcher, or a search field, and the footer for the signed-in user or the plan's usage. A menu in either works like one in the content. Here a large menu button opens a [dropdown](https://susonwaiba.github.io/htmx-ui/docs/components/dropdown); in the footer, `.dropdown-menu-up` opens it upwards. ```html ``` ## Content `.sidebar-content` fills the height between the header and the footer and scrolls when its groups don't fit. Make it the `

``` ## Menu action A `.sidebar-menu-action` is a small icon button at the end of an item, next to the menu button rather than inside it (a button can't hold another). Add `.sidebar-menu-action-hover` to show it only while the item is hovered or focused, or its menu is open; screens that can't hover always show it. To open a [dropdown](https://susonwaiba.github.io/htmx-ui/docs/components/dropdown), wrap the action in the dropdown and make it the trigger. ```html ``` ## Menu badge A `.sidebar-menu-badge` after the menu button shows a count or a short status at the end of the item. It ignores the pointer, so the whole item stays clickable. Screen readers read it after the link, so keep it meaningful on its own or add hidden text (``). ```html ``` ## Menu sub A `.sidebar-menu-sub` nests a list of `.sidebar-menu-sub-item`s with `.sidebar-menu-sub-button`s under an item, indented along a line. Usually it's the content of a [collapsible](https://susonwaiba.github.io/htmx-ui/docs/components/collapsible) item: the item is the collapsible, its menu button the trigger with a trailing `chevron-right`, which turns down while open. The current sub-item lights up its stretch of the line, like a branch of a tree. `.sidebar-menu-sub-button-sm` makes the text smaller. ```html ``` ## Menu skeleton `.sidebar-menu-skeleton` is a placeholder item for a menu that is still loading, with an optional `.sidebar-menu-skeleton-icon` and a `.sidebar-menu-skeleton-text` bar whose width is `--skeleton-width` (70% by default). It pulses, except with reduced motion. ```html ``` With htmx, render the skeleton in the page and let the menu replace itself once it's loaded. The server answers with the finished `

`). `.sidebar-input` goes with `.input` ([Input](https://susonwaiba.github.io/htmx-ui/docs/components/input)) for a compact field, such as a search box in the header. ```html ``` ## Trigger Any button with `data-sidebar-trigger` toggles the sidebar named by its `aria-controls`. Without `aria-controls` it toggles the sidebar of the `.sidebar-layout` it's in, and gets `aria-controls` set. Its `aria-expanded` is kept in sync: whether the sidebar is expanded, or, in mobile mode, whether the panel is open. `.sidebar-trigger` is a small ghost icon button for it; a `.btn` works as well. Give it an `aria-label`. ```html ``` A button with `data-sidebar-close` only closes: the mobile panel when it's open, else it collapses the sidebar. Use it for a close button inside the panel. ## Rail `.sidebar-rail` with `data-sidebar-rail` is a thin strip along the sidebar's inner edge. Hovering it shows a line and a resize cursor; clicking it toggles the sidebar. When the sidebar has slid off the screen the rail stays at the window's edge, so the sidebar can be brought back from there. It's a pointer shortcut, kept out of the tab order (`tabindex="-1"`): keyboard users have the trigger and [the shortcut](#keyboard). Put it last in the sidebar. It's hidden in mobile mode and with `data-collapsible="none"`. ## Side `data-side="right"` puts the sidebar on the right: its border, rail, slide direction and the inset's margin all follow. In a right sidebar, use `.tooltip-content-left` for icon-mode tooltips and the `panel-right` icon for the trigger. A layout can hold a sidebar on each side, each with its own trigger. ```html ``` ## Variant `data-variant` sets how the sidebar sits in the page: - `sidebar` (the default): a full-height column with a border on its inner edge. See the [preview](#preview). - `floating`: a rounded panel with a border and a shadow, inset from the window's edges. - `inset`: the sidebar blends into the page background, and the main area becomes a raised, rounded panel beside it. ```html ``` ## Collapsible `data-collapsible` sets what collapsing does: - `offcanvas` (the default): the sidebar slides fully out, and the main area takes the space. Once out of view it is hidden, so nothing in it can take focus. - `icon`: the sidebar shrinks to a rail of icons; see [Icon mode](#icon-mode). - `none`: it never collapses (on mobile it's still an off-canvas panel). The state is `data-state="expanded"` or `"collapsed"` on the sidebar. Render the one you want; the behaviour sets `expanded` when there's none. ```html ``` ## Icon mode and tooltips Collapsed with `data-collapsible="icon"`, the sidebar is `--sidebar-width-icon` wide. Menu buttons become squares showing just their icon, large ones just their avatar or logo; group labels, badges, actions, sub-menus and `.sidebar-input` hide. The labels stay in the page (clipped, not removed), so links keep their accessible names. For a tooltip, make the item a [tooltip](https://susonwaiba.github.io/htmx-ui/docs/components/tooltip) and add its text after the button. It only shows while the sidebar is collapsed to icons. It repeats the button's name, so hide it from screen readers with `aria-hidden="true"`; `Esc` still dismisses it. ```html ``` In icon mode the content doesn't scroll, so the tooltips and menus can reach outside it: keep the icons to what fits the height of the window. ## Width Three CSS variables set the widths. Set them on the sidebar, the layout or any ancestor, for example with Tailwind's arbitrary properties. | Variable | Description | | --- | --- | | `--sidebar-width` | Expanded width, 16rem by default. Floating and inset sidebars include their 0.5rem margin in it. | | `--sidebar-width-icon` | Width of the icon rail, 3rem by default (a 2rem button and its padding). | | `--sidebar-width-mobile` | Width of the mobile panel, 18rem by default. | | `--sidebar-top` | Where the sidebar sticks, and how much shorter than the window it is: the height of a header above it. 0 by default. | ```html ``` ## Mobile Below a breakpoint the sidebar becomes an off-canvas panel over the page, with a dimmed backdrop. The same trigger and shortcut open it. It closes on `Esc`, a click on the backdrop, following a link inside it, or a `data-sidebar-close` button. While it's open, focus moves into it (to the current page's link), stays there, the rest of the layout is inert and the page doesn't scroll; closing returns focus to the trigger. The panel always shows the full sidebar, whatever its desktop state. `data-breakpoint` picks the breakpoint: `sm` (40rem), `md` (48rem, the default), `lg` (64rem), or `none` to stay a column at every width. The switch is a media query on the window's width, in `sidebar.css`; the behaviour reads it from the stylesheet (the `--sidebar-mobile` custom property), so the two always agree, and it marks the sidebar `data-mobile` while it applies. The frame below is phone-sized: ## Keyboard | Key | Action | | --- | --- | | `Ctrl` `B` / `⌘` `B` | Toggles the sidebar (opens or closes the panel in mobile mode). Ignored while typing in a field. | | `Tab` `Shift` `Tab` | Moves through the links and buttons. Inside the open mobile panel, wraps around within it. | | `Enter` `Space` | Follows a link, presses a button, opens or closes a collapsible item or group. | | `Esc` | Closes the mobile panel and returns focus to the trigger; otherwise hides an icon-mode tooltip. | `data-shortcut="j"` moves the shortcut to another letter; `data-shortcut="none"` turns it off. Every sidebar listens for its own letter, so with two sidebars on a page give them different letters or turn one off. ## Persistence and server rendering With `data-cookie="sidebar_state"` (any cookie name) the behaviour stores the desktop state each time it changes: `true` for expanded, `false` for collapsed, for seven days, on path `/`, `SameSite=Lax`. On load it restores a stored state without animating. Without `data-cookie` nothing is stored. The behaviour only runs once the page has loaded, so a page that renders the sidebar expanded and is then restored to collapsed would show it open for a moment. Render the stored state instead. On a server, read the cookie and pass it to the template (see [rendering a page per request](https://susonwaiba.github.io/htmx-ui/docs/servers/rendering#render-per-request)): ```ts server.ts app.get("/dashboard", ({ request }) => { const collapsed = /(?:^|;\s*)sidebar_state=false/.test(request.headers.get("cookie") ?? ""); return html(site.render("/dashboard", { sidebarState: collapsed ? "collapsed" : "expanded" })); }); ``` ```html pages/dashboard.html ``` A static site has no request to read, so set the state from the cookie with a small inline script as the sidebar's first child. It runs before the page is painted: ```html Static pages ``` ## Theming The sidebar has its own colour tokens, so it can be tinted apart from the page. By default they follow the page's ([Theming](https://susonwaiba.github.io/htmx-ui/docs/theming#tokens)), with a slightly darker background in light mode. Override them on `:root`, under `.dark`, or on one sidebar. Each is also a Tailwind colour: `bg-sidebar`, `text-sidebar-primary`, `border-sidebar-border`… | Token | Description | | --- | --- | | `--sidebar` | Background. zinc-50 in light mode, zinc-900 in dark. | | `--sidebar-foreground` | Text and icons. Defaults to --foreground. | | `--sidebar-primary` | Accent fills, such as a logo tile. Defaults to --primary. | | `--sidebar-primary-foreground` | Text on --sidebar-primary. | | `--sidebar-accent` | Hovered and current items. Defaults to --accent. | | `--sidebar-accent-foreground` | Text on --sidebar-accent. | | `--sidebar-border` | Borders, the sub-menu line, separators, the rail. Defaults to --border. | | `--sidebar-ring` | Focus rings. Defaults to --ring. | ```css /* A dark sidebar in both themes */ .sidebar { --sidebar: var(--color-zinc-900); --sidebar-foreground: var(--color-zinc-300); --sidebar-accent: var(--color-zinc-800); --sidebar-accent-foreground: var(--color-white); --sidebar-border: var(--color-zinc-800); } ``` ## Accessibility - The `

` is a complementary landmark; give it an `aria-label`. Make the part holding the site's links a `

` with its own label. - Mark the current page with `aria-current="page"`: it's both what screen readers announce and the style hook. - Menus are lists of links and buttons, not ARIA menus, so `Tab` moves through them as through any navigation. Collapsible items and groups are disclosure buttons with `aria-expanded`. - The trigger is a button with `aria-controls` and an `aria-expanded` that follows the sidebar. Label it. - Collapsed to icons, labels are clipped rather than removed, so links keep their names; the tooltips that repeat them are `aria-hidden`, appear on keyboard focus too, and `Esc` hides them. - A sidebar slid off the screen and a closed mobile panel are hidden, so nothing in them can be focused. - The open mobile panel keeps focus inside it and makes the rest of the layout inert; closing it returns focus to where it was. - Action buttons need an `aria-label` naming their item ("Options for Checkout swaps"), since several share an icon. - With reduced motion the sidebar switches states without animating. ## htmx The behaviour runs again on every element htmx inserts (`initComponents` on `htmx:after:process`), so a sidebar, a trigger or a menu returned by the server works without extra code, and the existing triggers follow a sidebar that was replaced. Load slow parts of the menu after the page, as in [Menu skeleton](#menu-skeleton): the fragment the server returns is ordinary sidebar markup. ```html The fragment for hx-get="/fragments/saved-views" ``` With `hx-boost`, mark the current link from the page being rendered (`aria-current="page"`) as usual; following a link closes the mobile panel before the new page is swapped in. ## Events Every change fires a bubbling `sidebar:toggle` event on the sidebar, with `detail` `{ expanded, open, mobile }`: the desktop state, whether the mobile panel is open, and whether the sidebar is in mobile mode. To toggle it from a script, click its trigger. ```js document.addEventListener("sidebar:toggle", (e) => { console.log(e.target.id, e.detail.expanded ? "expanded" : "collapsed"); }); document.querySelector("[data-sidebar-trigger]").click(); ``` ## The docs navigation The navigation of these docs is a sidebar composed for a docs site: it never collapses on a desktop (`data-collapsible="none"`), it's an off-canvas panel below `lg` opened by the header's menu button, it sticks under the 56px header with `--sidebar-top`, and its colours come from the tokens: transparent from `lg` up, with muted links. ```html layouts/docs.html (shortened) ``` ## Upgrading from 0.1 The sidebar of 0.1 was a single navigation column. Its classes map to the new parts: | 0.1 | Description | | --- | --- | | `.sidebar-label` | .sidebar-group-label (inside a .sidebar-group). | | `.sidebar-link` | .sidebar-menu-button, in a

of a

Change your name and email address.

Overview panel

Today's numbers.

The rendered result.

Aligned left.

Free plan.

Name, language and time zone.

`), restored on the next visit, and followed in other open browser tabs. The package-manager tabs on code blocks use `data-tabs-sync="pm"`. Switch one of these two: ```html

Group 1: HTML panel

Group 2: HTML panel

``` ## Lazy panels with htmx Load a panel's content the first time it's shown with `hx-trigger="intersect once"`: ```html

Rendered with the page.

``` ## Reference | Class | Description | | --- | --- | | `.tabs` | Wrapper: spaces the list and panels; side by side when vertical. | | `.tabs-list` | Segmented control holding the tab buttons. | | `.tabs-trigger` | Tab button; selected style comes from aria-selected="true", faded when disabled. | | `.tabs-panel` | Panel focus ring. | | `.tabs-line / .tabs-pills / .tabs-outline` | Underlined, primary-filled and bordered variants of .tabs-list. | | `.tabs-full` | List and triggers stretched to the full width. | | `[data-tabs]` | Behaviour: wires up a tab group. | | `[data-orientation="vertical"]` | On .tabs: list beside the panels, Up/Down keys. | | `[data-tab] / [data-tab-panel]` | Matching values pair a tab with its panel. | | `[data-tabs-sync="key"]` | Sync groups with the same key and remember the choice. | --- title: "Alert dialog" description: "A modal dialog that interrupts the user with important content and expects a response." url: "/docs/components/alert-dialog" section: "Components" --- # Alert dialog A modal dialog that interrupts the user with important content and expects a response. ```html ``` ## Markup An alert dialog is a [dialog](https://susonwaiba.github.io/htmx-ui/docs/components/dialog) with `role="alertdialog"`: the same classes, the same behaviour, the same ways to open it. The role changes two things. Screen readers announce it as an alert, and a click outside doesn't close it, because the user has to answer. `Esc` still closes it, as a cancel. - Give it a title and a description, linked with `aria-labelledby` and `aria-describedby`. - Leave out the corner close button; the footer's buttons are the answers. - Put `autofocus` on the least destructive button, usually Cancel, so `Enter` can't confirm by accident. - Give each button a `data-dialog-close` value. It becomes the dialog's `returnValue`, which tells the `close` event which answer was given. ## Small `.dialog-sm` makes it narrower, centres the text and sets the two buttons side by side at equal width. ```html ``` ## Media `.dialog-media`, first in the header, adds an icon or an image. In the default size it sits beside the title and description from the `sm` breakpoint, and above them on smaller screens. ```html ``` ## Small with media In a small alert dialog the media is centred above the title. It can hold an image as well as an icon. ```html ``` ## Destructive For an action that destroys something, make the confirming button `.btn-danger` and tint the media with `.dialog-media-danger`. Name the action on the button (“Delete chat”), not just “Continue”. ```html ``` ## Confirming an htmx request Put the request on the confirming button. `data-dialog-close` closes the dialog at once and htmx sends the request; the response goes to the button's `hx-target`. ```html ``` To act on the answer in your own script instead, listen for the dialog's `close` event and read `returnValue`: ```ts const dialog = document.querySelector("#alert-basic")!; dialog.addEventListener("close", () => { if (dialog.returnValue === "continue") deleteAccount(); dialog.returnValue = ""; // reset for the next time it opens }); ``` ## Macro `dialog()` with `alert=true` writes an alert dialog: the role, no corner button, and the header with optional media. ```jinja {% from "components/dialog/dialog.html" import dialog %} {% call dialog("delete-project", "Delete project?", "All of its pages and files will be removed.", alert=true, size="sm", media="trash", media_variant="danger") %} {% endcall %} ``` ## Reference Alert dialogs use the [dialog classes](https://susonwaiba.github.io/htmx-ui/docs/components/dialog#reference). These are the parts specific to them: | Class | Description | | --- | --- | | `role="alertdialog"` | On the .dialog: announced as an alert, and a click outside doesn't close it. | | `.dialog-sm` | Narrow, centred text, buttons side by side at equal width. | | `.dialog-media` | Icon or image first in the header: beside the title in the default size from sm, centred above it in .dialog-sm. | | `.dialog-media-danger` | Danger-tinted media, for destructive actions. | | `[data-dialog-close="value"]` | An answer button: closes the dialog and sets returnValue. | --- title: "Dialog" description: "A window overlaid on the page or on another dialog, rendering the content underneath inert. Built on the native

Learn more

…icon…

No projects yet

…

…buttons, an input…

Cloud storage empty

Upload files to your cloud storage to access them anywhere.

No notifications

You're all caught up. New notifications will appear here.

Kofi is offline

Kofi is away right now. Leave a message and they'll see it when they're back.

No team members

Invite your team to collaborate on this project.

404 – Page not found

The page you're looking for doesn't exist. Try searching for what you need below.

Need help? Contact support

Activity

No activity this week

Activity from your projects shows up here.

Payment methods

Cards and accounts you pay with.

No payment methods

Add a card to pay for your subscription.

Invoice	Status	Amount
No invoices found No invoices match “acme”. Try another search, or clear the filters.

Invoice	Status	Amount
No invoices yet Invoices you send show up here.

…icon…

Couldn't load the feed

Check your connection and try again.

No messages

New messages show up here.

` in small panels and table cells. - Media is decorative: the icon is hidden from screen readers, and avatars take `aria-hidden="true"`. Say everything that matters in the title and description. - Write button labels that make sense on their own: “Create project”, not “Get started”. - When an empty state replaces results that were there a moment ago (after a search), announce it: swap it into a container with `aria-live="polite"`. ## Reference | Class | Description | | --- | --- | | `.empty` | Centred column with padding (more from md) that grows to fill its container. | | `.empty-outline` | Dashed border. | | `.empty-muted` | Muted background that fades out towards the bottom. | | `.empty-sm` | Compact: less padding, smaller gaps, icon square and title. | | `.empty-header` | Media, title and description; at most 24rem wide. | | `.empty-media` | Holds an icon, an .avatar (shown at 3rem) or an .avatar-group (large, grey). | | `.empty-media-icon` | A muted rounded square around an icon. | | `.empty-title` | What is missing. | | `.empty-description` | Muted text below the title. Links are underlined. | | `.empty-content` | Actions and inputs: a centred column, at most 24rem wide. | --- title: "Loader" description: "Pure-CSS loading indicators in eight styles, from bouncing dots and waves to shimmering text, tuned with custom properties." url: "/docs/components/loader" section: "Components" --- # Loader Pure-CSS loading indicators in eight styles, from bouncing dots and waves to shimmering text, tuned with custom properties. ```html

pulse

pulse-dot

dots

typing

wave

text-blink

text-shimmer

loading-dots

`s (three for `.loader-dots` and `.loader-typing`, five for `.loader-wave`), each `aria-hidden="true"`. The pulse variants have no children: the element itself is the shape. - Give the loader `role="status"` and an accessible name: `aria-label`, or `` text after the dots. The text variants show their own text, which is read out. - The [`loader()` macro](#macro) writes all of this for you. ```html ``` ## Shapes `.loader-pulse` is a ring that breathes in and out; `.loader-pulse-dot` a single dot. `.loader-dots` bounces three dots, `.loader-typing` fades them in turn like a chat typing indicator, and `.loader-wave` raises and lowers a row of bars. ```html ``` ## Text The text variants animate the words themselves, in the muted text colour at the surrounding font size. `.loader-text-blink` fades the text in and out, `.loader-text-shimmer` sweeps a light band across it, and `.loader-loading-dots` writes an ellipsis one dot at a time. ```html Fetching results Thinking about your question Generating ``` ## Sizes `.loader-sm` and `.loader-lg` make the shapes 12px and 24px tall instead of 16px, and set the text variants in `text-xs` and `text-base`. For any other size set `--loader-size`; dots and bars are sized from it. ```html

Small Default Large

``` ## Customisation Every variant reads its look from custom properties on the `.loader`. Set them in a `style` attribute, or with Tailwind's arbitrary properties such as `[--loader-duration:2s]`. - `--loader-size`: the height of the shapes (`1rem`). - `--loader-duration`: one cycle of the animation (`1.2s`; the text variants `2s`, loading dots `1.4s`). The dots' and bars' stagger follows it. - `--loader-color`: the colour. Shapes use the current text colour, so `text-*` utilities work too; the text variants default to `muted-foreground`. - `--loader-highlight` and `--loader-spread`: the colour of the shimmer's light band (`foreground`) and its half-width, as a share of the sweep (`20%`). ### Speed ```html ``` ### Colour ```html Saving ``` ### Shimmer band A wider `--loader-spread` softens the band; a contrasting `--loader-highlight` tints it. ```html A narrow, sharp band A wide, soft band Tinted with the primary colour ``` > With `prefers-reduced-motion` set, nothing moves: every variant fades its opacity slowly instead, so the loader still reads as busy. ## In a button Shapes sit in a `.btn` like an icon. When the button text already says what's happening, pass `label=none` so the loader is hidden from screen readers. ```html ``` ## With htmx requests Add `.htmx-indicator` to show a loader only while a request runs. Inside a button it takes no space until then, and `.htmx-indicator-hide` swaps out an icon for it, as with the [spinner](https://susonwaiba.github.io/htmx-ui/docs/components/spinner#htmx). ```html

Refreshing

``` > The `/api/slow` endpoint is a mock that only exists under `bun run dev`. ## Macro `loader()` writes the variant's children, `role="status"` and the accessible name. Shapes are read out as `label`; text variants show `text` (or the label) and are read as it. ```jinja {% from "components/loader/loader.html" import loader %} {{ loader() }} {# three bouncing dots, "Loading" #} {{ loader("wave", size="lg", label="Uploading") }} {{ loader("text-shimmer", text="Thinking") }} {{ loader("pulse", label=none) }} {# decorative #} {{ loader("typing", class="htmx-indicator", attrs={"id": "typing"}) }} ``` ## Reference | Class | Description | | --- | --- | | `.loader` | The base: an inline flex box that holds the custom properties below. | | `.loader-pulse` | A ring breathing in and out. | | `.loader-pulse-dot` | A single pulsing dot. | | `.loader-dots` | Three bouncing dots (three child spans). | | `.loader-typing` | Three dots fading in turn, a typing indicator (three child spans). | | `.loader-wave` | Bars rising and falling (five child spans). | | `.loader-text-blink` | Text fading in and out. | | `.loader-text-shimmer` | Text with a light band sweeping across it. | | `.loader-loading-dots` | Text followed by "..." written one dot at a time (three child spans). | | `.loader-sm / .loader-lg` | 12px or 24px shapes; text-xs or text-base text. | | `--loader-size` | The height of the shapes (1rem). | | `--loader-duration` | One animation cycle (1.2s; text 2s, loading dots 1.4s). | | `--loader-color` | The colour (currentColor; text variants muted-foreground). | | `--loader-highlight / --loader-spread` | The shimmer band's colour (foreground) and half-width (20%). | | Macro | Description | | --- | --- | | `loader(variant="dots", text=none, size=none, label="Loading", class="", attrs=none)` | Writes a loader. label=none hides a shape from assistive technology; text sets a text variant's words. | --- title: "Progress" description: "Displays an indicator showing the completion progress of a task, typically displayed as a progress bar." url: "/docs/components/progress" section: "Components" --- # Progress Displays an indicator showing the completion progress of a task, typically displayed as a progress bar. ```html 33% ``` ## Markup - A native `` with `value` and `max` (1 if left out). The browser exposes it as a progress bar with its percentage; no ARIA attributes are needed. - Give it an accessible name: a `` (see [Label and value](#label-and-value)), or `aria-label`. - The text inside is a fallback for browsers that don't draw progress bars. - It fills its container's width; set another with a width utility (`w-3/5` above). ## Label and value `.progress-field` lays out a `.progress-label` and a `.progress-value` above the bar, and a `.progress-description` below it. Each part is optional. The value repeats what the bar already announces, so it is `aria-hidden`; the description is linked with `aria-describedby`. ```html

Uploading files 66%

6 of 9 files, about a minute left.

Storage 72%

``` ## Indeterminate Leave out `value` when the amount of work isn't known yet: a bar slides along the track. With reduced motion, the track is striped instead, still and full width, so it can't be read as a value. ```html

Preparing export…

``` ## Sizes `.progress-sm` is 4px high, the default 8px and `.progress-lg` 12px. ```html 40% 60% 80% ``` ## Colours `.progress-success`, `.progress-warning` and `.progress-danger` use the status colours; the track is the same colour, faded. For any other colour, set `--progress-tone`. Colour alone doesn't say what is wrong, so put that in the label or description too. ```html

Tests passed 100%

Monthly quota 85%

Nearly used up. It resets on the 1st.

Disk 97%

Almost full: delete old backups to free space.

50% ``` ## Macro `progress()` writes the bar, and the field around it when there is a label, value or description, with the ids wired up and the percentage worked out (rounded, and kept within 0–100%). ```jinja {% from "components/progress/progress.html" import progress %} {{ progress(3, max=9, label="Uploading files", show_value=true, description="3 of 9 files") }} {{ progress(aria_label="Loading") }} ``` renders: ```html

Uploading files 33%

3 of 9 files

``` | Parameter | Description | | --- | --- | | `value` | The current value. Left out (or none): indeterminate. | | `max=100` | The value at completion. | | `label` | A visible . Without one, pass aria_label. | | `aria_label` | The accessible name when there is no visible label. | | `show_value=false` | true shows the percentage beside the label (aria-hidden). | | `description` | Help text under the bar, linked with aria-describedby. | | `id` | The id. Defaults to one made from the label (progress-uploading-files); pass it when two bars on a page share a label. | | `size` | "sm" or "lg". | | `variant` | "success", "warning" or "danger". | | `attrs` | More attributes for the outer element, as a dict, e.g. {"hx-get": "/jobs/42/progress"}. | | `class` | More classes on the outer element: the .progress-field, or the when there is no field. | ## With htmx For a job running on the server, let the progress fragment fetch its own replacement. Each response is the field at its new value, polling again after a short delay; the last one leaves the polling attributes out, which stops it. Start it with a button whose `hx-post` starts the job and returns the first fragment. ```html

Exporting invoices 40%

Exporting invoices 100%

Done. Download the CSV

``` The bar's width animates from the old value to the new one only when the same element is updated. Swapping in a new `` jumps to the new width, which is fine for polling. The [Attachment](https://susonwaiba.github.io/htmx-ui/docs/components/attachment) component uses the same polling pattern for uploads. ## Accessibility - `` has the `progressbar` role and reports its value as a percentage, or as busy when indeterminate. - Screen readers don't announce every change of value. Announce the end of a task (or a failure) in a `role="status"` element, as in the htmx example. - When the value is more meaningful as text ("Step 2 of 5"), set `aria-valuetext="Step 2 of 5"` on the ``. - An indeterminate bar standing in for content that is loading needs a name saying what is loading ("Loading invoices"), not just "Loading". ## Reference | Class | Description | | --- | --- | | `.progress` | On a : a rounded track; the bar is the value. No value: indeterminate. | | `.progress-sm / .progress-lg` | 4px / 12px high (8px by default). | | `.progress-success / -warning / -danger` | Status colours for the bar and track. | | `--progress-tone` | The bar colour (the track is it at 20%). Defaults to --primary. | | `.progress-field` | Grid laying out a label and value above the bar and a description below. | | `.progress-label` | The naming the bar, on the left. | | `.progress-value` | The value as text, on the right; aria-hidden when it repeats the percentage. | | `.progress-description` | Help text under the bar, linked with aria-describedby. | --- title: "Skeleton" description: "Placeholders in the shape of content that is still loading: any shape from utilities, ready-made avatars, text, cards, lists, tables and forms." url: "/docs/components/skeleton" section: "Components" --- # Skeleton Placeholders in the shape of content that is still loading: any shape from utilities, ready-made avatars, text, cards, lists, tables and forms. ```html

``` ## Markup - `.skeleton` is a muted, pulsing block. Its shape is yours: size it with utilities (`h-4 w-48`, `size-12`, `aspect-video`), round it with `.skeleton-circle` or any `rounded-*`. - Mark the loading region `aria-busy="true"` with a text alternative (``, or `role="status"` and a label), and the shapes `aria-hidden="true"`: they mean nothing read aloud. - No JavaScript: the skeleton is whatever stands in the page until htmx swaps the real content over it. ## Shapes Ready-made shapes take the size of the thing they stand for: `.skeleton-avatar` (as `.avatar-lg`), `.skeleton-button` and `.skeleton-input` (as `.btn` and `.input`), `.skeleton-badge`, `.skeleton-image` (16:9). Utilities still resize them. ```html ``` ## Text `.skeleton-text` is one line, `1em` high, so it follows the font size it sits in; `.skeleton-heading` is a heading-sized line at half width. Stack lines in `.skeleton-lines` and the last one comes out shorter, like the end of a paragraph. ```html ``` ## Animation Shapes pulse. `.skeleton-shimmer`, on a shape or on any ancestor, sweeps a highlight across instead; `.skeleton-static` stops the motion. Both stop for readers who prefer reduced motion. ```html ``` ## Avatar, card, list, table and form Macros in `components/skeleton/skeleton.html` build common placeholders from these shapes, each as a loading region (`role="status"`, `aria-busy`, a hidden "Loading…"). They take `label`, `shimmer` and `class`. ```jinja {% from "components/skeleton/skeleton.html" import skeleton_text, skeleton_avatar, skeleton_card, skeleton_list, skeleton_table, skeleton_form %} {{ skeleton_avatar(lines=2) }} {{ skeleton_card(media=true, lines=2, footer=true, shimmer=true) }} {{ skeleton_list(items=3, avatar=true) }} {{ skeleton_table(rows=4, columns=4) }} {{ skeleton_form(fields=2) }} {{ skeleton_text(lines=3, label="Loading the article…") }} ``` ## With htmx Put the skeleton where the content will go and let htmx replace it: `hx-trigger="load"` fetches straight away (`revealed` when it scrolls into view) and `hx-swap="outerHTML"` swaps the placeholder for the response. ```html

``` For a reload of content already on the page, show a skeleton as the request's indicator: `hx-indicator` points at it, and the `.htmx-indicator` class keeps it hidden until a request is in flight. ## Reference | Class | Description | | --- | --- | | `.skeleton` | A muted block that pulses; shape it with utilities. | | `.skeleton-circle` | Fully rounded. | | `.skeleton-text / .skeleton-heading` | A line of text (1em high), a heading line (1.5em, half width). | | `.skeleton-lines` | A paragraph of .skeleton-text; the last line is shorter. | | `.skeleton-avatar / -button / -input / -badge / -image` | Shapes sized like those components. | | `.skeleton-shimmer` | On a shape or an ancestor: a sweeping highlight instead of the pulse. | | `.skeleton-static` | No animation. | | `skeleton_text() … skeleton_form()` | Macros: placeholders for text, avatars, cards, lists, tables and forms. | --- title: "Spinner" description: "An indicator that shows a loading state. Any icon can spin, or use a pure-CSS ring when there is no icon to hand." url: "/docs/components/spinner" section: "Components" --- # Spinner An indicator that shows a loading state. Any icon can spin, or use a pure-CSS ring when there is no icon to hand. ```html ``` ## Usage Add `.spinner` to an SVG icon and it spins. The `spinner()` macro inlines an icon from `icons/` with the class and accessibility attributes set: `role="status"` and an `aria-label` of "Loading". ```html ``` ## Custom icon Pass any icon name to the macro, or put `.spinner` on your own SVG. ```html ``` ## Without an icon On any element other than an SVG, `.spinner` draws a ring with CSS. Use it in markup that can't inline icons, such as HTML fragments built by your server. ```html ``` ## Sizes Use `.spinner-sm` (12px), the default (16px), `.spinner-lg` (24px) and `.spinner-xl` (32px), or any `size-*` utility. ```html ``` ## Colour Spinners use the current text colour, so `text-*` utilities recolour them. ```html ``` ## In a button Inside a `.btn`, the spinner takes the button's icon size. When the button text already says what's happening, pass `label=none` so the spinner is hidden from screen readers. `aria-busy="true"` makes the button ignore clicks without fading it like `disabled` does. ```html ``` ## In a badge ```html Syncing Deploying Updating ``` ## In a button group ```html

``` ## In an input group ```html

``` ## With htmx requests Add `.htmx-indicator` to show a spinner only while a request runs. Inside a button, badge or input-group addon it takes no space until then. Add `.htmx-indicator-hide` to an icon to swap it for the spinner. ```html

``` > The `/api/slow` endpoint is a mock that only exists under `bun run dev`. ## Reference | Class | Description | | --- | --- | | `.spinner` | Spins an SVG icon. On any other element, draws a CSS ring. | | `.spinner-sm / -lg / -xl` | 12px, 24px or 32px instead of 16px. | | `.htmx-indicator-hide` | Hidden while the htmx request it's inside runs. | | Macro | Description | | --- | --- | | `spinner(icon="loader", class="", label="Loading", id=none)` | Inlines icons/.svg as a spinner. label=none hides it from assistive technology. | --- title: "Toast" description: "A short message that stacks in a corner and leaves on its own: success, info, warning, error and loading types, actions, promises, swipe to dismiss, and toasts sent by the server." url: "/docs/components/toast" section: "Components" --- # Toast A short message that stacks in a corner and leaves on its own: success, info, warning, error and loading types, actions, promises, swipe to dismiss, and toasts sent by the server. ```html ``` ## How it works - Toasts stack in a corner, newest in front, the next two peeking out behind it. Hover or focus the stack to fan it out; that also pauses their timers (as does switching browser tab). - Each slides in from its edge and leaves after 4 seconds, or when closed with its × (on hover), swiped towards the edge, or `Esc` while focused. `Alt`+`T` moves focus to the newest one. - The toasts sit in a live region, so screen readers read them out; errors are `role="alert"`. - Show one from script with `toast()`, from markup with `data-toast`, or from the server with an `HX-Trigger` header. No markup is needed in the page: the toaster is created with the first toast. ## Types `data-toast-type` (or `toast.success()` and friends) sets the icon and its colour: `success`, `info`, `warning`, `error` and `loading`, which spins and stays until it's updated or dismissed. ```html ``` ## Action and cancel `data-toast-action="Undo"` adds a button that dismisses the toast and fires `toast:action` on the element that showed it, so `hx-trigger="toast:action"` can send a request; `data-toast-cancel` adds a quieter one that fires `toast:cancel`. From script, pass `action` / `cancel` with an `onClick` (call `event.preventDefault()` to keep the toast open). ```html

Archive, then Undo: the request goes out from the toast.

``` ## From script `toast(message, options)` returns the toast's id. Showing another toast with the same `id` updates that one in place. ```ts app.ts import { toast } from "htmx-ui"; toast("Event has been created", { description: "Sunday, December 3 at 9:00 AM", action: { label: "Undo", onClick: () => undo() }, }); toast.success("Saved"); // also .info, .warning, .error, .loading const id = toast.loading("Uploading…"); toast.success("Uploaded", { id }); // replaces the loading toast toast.dismiss(id); // or toast.dismiss() for all // Loading, then success or error when the promise settles toast.promise(fetch("/api/save", { method: "POST" }), { loading: "Saving…", success: (res) => `Saved (${res.status})`, error: "Could not save", }); ``` | Option | Description | | --- | --- | | `type` | "default" \| "success" \| "info" \| "warning" \| "error" \| "loading". | | `description` | A second, muted line. | | `duration` | Milliseconds before it leaves (default 4000; loading: Infinity). Infinity keeps it. | | `action / cancel` | { label, onClick(event) }: buttons that dismiss the toast unless onClick calls preventDefault(). | | `id` | Update the toast with this id instead of adding one. | | `position` | top-left, top-center, top-right, bottom-left, bottom-center or bottom-right. | | `dismissible` | false: no close button, swipe or Escape. | | `closeButton / icon` | false hides the close button / the type's icon. | | `onDismiss / onAutoClose` | Called with the id when the reader dismisses it / its timer ends. | | `class` | More classes on the toast. | ## An htmx request `data-toast-loading` on the element that makes a request shows a loading toast while it runs, which becomes `data-toast-success` or `data-toast-error` (any status from 400) when it finishes. Leave one out and the toast just goes. ```html ``` ## From the server Send a `toast` event in the `HX-Trigger` response header, with the options as its value (a string is taken as the message): ```http HX-Trigger: {"toast": {"message": "Profile updated", "type": "success", "description": "Saved at 09:41."}} ``` ```html ``` htmx fires the event on the element that made the request. If the response swaps that element out, it never reaches the page, so add `"target": "body"` to the value. Or return an element instead: `` shows its toast as it's swapped in and removes itself, which suits an `hx-swap-oob` fragment. ## Position and the toaster Place a `

` anywhere in your layout to change the defaults: `data-position`, `data-duration`, `data-visible` (toasts shown in the stack, 3), `data-expand` (always fanned out), `data-close-button="false"` and `data-rich-colors` (tint the whole toast by its type). A toast's own `position` (`data-toast-position`) overrides the toaster's. ```html ``` ```html layouts/base.html

``` Width, spacing and distance from the edge are CSS variables on `.toaster-list`: `--toast-width` (356px), `--toast-gap` (14px) and `--toast-inset` (1.5rem). On narrow screens toasts span the width. ## Reference | Class | Description | | --- | --- | | `toast(message, options)` | Show a toast (or update one by id); returns its id. | | `toast.success / info / warning / error / loading` | toast() with that type. | | `toast.promise(promise, { loading, success, error })` | A loading toast that turns into the outcome. | | `toast.dismiss(id?)` | Dismiss one toast, or all. | | `[data-toast="message"]` | Shows a toast on click; data-toast-type, -description, -duration, -position, -action, -cancel, -id. | | `[data-toast-loading] / -success / -error` | On an element making an htmx request: loading toast, then the outcome. | | `[data-toast-show="message"]` | An element that shows a toast when it's added to the page, then removes itself. | | `HX-Trigger: {"toast": …}` | A toast from a response header. | | `toast:action / toast:cancel` | Fired on the trigger element when the toast's buttons are clicked. | | `[data-toaster]` | The toaster's defaults: data-position, -duration, -visible, -expand, -close-button, -rich-colors. | | `.toast, .toast-title, .toast-description, .toast-action …` | The toast's parts, to restyle; data-type on .toast. | --- title: "Accordion" description: "A vertically stacked set of headings that each reveal a section of content. Built on

, so it works without JavaScript." url: "/docs/components/accordion" section: "Components" --- # Accordion A vertically stacked set of headings that each reveal a section of content. Built on

, so it works without JavaScript. ```html

Is it accessible?

Yes. It's a native <details> element, so keyboards and screen readers handle it out of the box.

Does it need JavaScript?

No. Opening, closing and "one at a time" are all done by the browser. An optional behaviour fully locks disabled items.

Can it load content from the server?

Yes, with htmx. See the example further down.

``` ## Markup - Each item is a `

` with a `

` heading and a `.accordion-content` body. Wrap the items in `.accordion`. - Add `open` to an item to show it expanded on load. - On older browsers that can't animate to `height: auto`, items open instantly instead of sliding. ## One open at a time Give every item the same `name`. Opening one closes the others, as in the example above. Use a different name for each accordion on the page. ## Multiple open Leave `name` out, and each item opens and closes on its own. ```html

Shipping

Orders ship within two business days.

Returns

Return anything within 30 days for a full refund.

Warranty

Two years on every product, parts and labour.

``` ## Disabled Add `aria-disabled="true"` and `tabindex="-1"` to the summary: it fades, ignores pointer clicks and drops out of the tab order. Screen readers and scripts can still activate a `

`, so also put `data-accordion` on the wrapper. Its one-line behaviour stops a disabled summary from opening its item. ```html

Available

This one opens.

Locked until you upgrade

Hidden content.

Also available

So does this one.

``` ## Borders `.accordion-bordered` draws a box around the accordion. `.accordion-separated` gives each item its own box. ```html

Billing

Invoices go out on the first of each month.

Security

All data is encrypted at rest and in transit.

Integrations

Connect over webhooks or the REST API.

Separated item

Each item is its own box.

Another item

With space between them.

``` ## Loading content with htmx `

` fires a `toggle` event when it opens. `hx-trigger="toggle once"` fetches the body the first time the item is opened. ```html

Server message

Loading…

``` ## Reference | Class | Description | | --- | --- | | `.accordion` | Wrapper around the items. Add data-accordion when any item is disabled. | | `.accordion-item` | On

. Same name on several items: only one open at a time. | | `.accordion-trigger` | On

. Draws the chevron. aria-disabled="true" + tabindex="-1" disables it. | | `.accordion-content` | The revealed body. | | `.accordion-bordered` | Box around the whole accordion, with padded rows. | | `.accordion-separated` | Each item in its own box. | --- title: "Card" description: "Displays a card with a header, content and footer, plus optional media, a header action and scrolling content." url: "/docs/components/card" section: "Components" --- # Card Displays a card with a header, content and footer, plus optional media, a header action and scrolling content. ```html

Log in to your account

Enter your email below to log in.

``` ## Parts Every part is optional. `.card` itself has no padding; the header, content and footer each pad themselves, so media, tables and lists can run edge to edge. - `.card-header` holds `.card-title` and `.card-description`. - `.card-action`, inside the header, sits in its top-right corner beside the title and description. - `.card-content` is the body. `.card-footer` is a row for actions, pinned to the bottom of tall cards. ```html

Notifications

You have 3 unread messages.

Your call has been confirmed. Your subscription is expiring soon.

``` ## Image `.card-image` on an `` (or video, or any media block) runs it edge to edge. As the first or last child, its outer corners follow the card's. ```html

Weekend in the mountains

Two nights, guided hikes, all meals.

New

Image at the bottom

Last child, so the bottom corners round.

``` ### Horizontal `.card-horizontal` puts the media beside the text from the `sm` breakpoint. Wrap the other parts in `.card-body`. ```html

Alpine route

12 km, 800 m of climbing.

A full-day loop past three lakes. Start early.

``` ## Scrolling content Add `.card-scroll` to `.card-content` to give long content its own scrollbar while the header and footer stay put. Limit the height on the card (`h-80`, `max-h-96`…) or on the content (`max-h-48`). ```html

Terms of service

Last updated October 2026.

By using the service you agree to these terms. Please read them carefully.

You are responsible for the content you publish and for keeping your account secure.

We may change the service at any time. We'll tell you about significant changes in advance.

We can suspend accounts that break these terms, after warning you where we reasonably can.

The service is provided as is, without warranties of any kind.

These terms are governed by the laws of the place where we are registered.

``` ## Size `.card-sm` uses tighter padding. ```html

Small card

16px padding instead of 24px.

Good for dense dashboards.

``` ## Clickable card Make the whole card an `` and add `.card-link` for a hover state. ```html

All components

Browse every component in the library.

``` ## Loading content with htmx Cards make good swap targets. This one fetches its body from the server: ```html

Server message

Fetched with hx-get.

``` ## Reference | Class | Description | | --- | --- | | `.card` | Container: border, surface colour, radius and shadow. | | `.card-header` | Top section, padded on three sides. | | `.card-title` | Heading text. | | `.card-description` | Muted supporting text. | | `.card-action` | Inside the header: top-right slot beside the title and description. | | `.card-content` | Main body, padded on all sides. | | `.card-scroll` | On .card-content: scrolls on its own when the card or content has a height limit. | | `.card-footer` | Bottom row for actions; pinned to the bottom of tall cards. | | `.card-image` | Edge-to-edge media; outer corners follow the card's. | | `.card-horizontal` | Media beside the content from the sm breakpoint. Wrap the parts in .card-body. | | `.card-sm` | Tighter padding. | | `.card-link` | Hover style for cards that are links. | --- title: "Carousel" description: "Slides that drag, swipe and snap with momentum, on Embla Carousel: item sizes, spacing, vertical orientation, options and plugins." url: "/docs/components/carousel" section: "Components" --- # Carousel Slides that drag, swipe and snap with momentum, on Embla Carousel: item sizes, spacing, vertical orientation, options and plugins. ```html

``` ## Installation The carousel runs on [Embla Carousel](https://www.embla-carousel.com), a dependency of htmx-ui that is loaded only on pages with a carousel. Plugins are separate packages; add the ones you use: ```bash bun bun add embla-carousel-autoplay ``` ```bash npm npm install embla-carousel-autoplay ``` ```bash pnpm pnpm add embla-carousel-autoplay ``` ```bash yarn yarn add embla-carousel-autoplay ``` ## Markup - `.carousel[data-carousel]` holds a `.carousel-viewport` (it clips), a `.carousel-container` (it moves) and the `.carousel-item`s. - `[data-carousel-prev]` and `[data-carousel-next]` buttons scroll, and disable themselves at the ends. Give them an `aria-label`, and [`.btn-no-press`](https://susonwaiba.github.io/htmx-ui/docs/components/button#press) so they don't nudge when pressed. - The behaviour marks the carousel as a region and each item as a slide ("2 of 5"); name the region with `aria-label`. `←` `→` scroll when focus is inside it. - Without JavaScript the slides are a clipped row; give the viewport `overflow-x-auto` if they must stay reachable then. ## Item size Items fill the viewport. Size them with `basis-*` utilities on the items (responsive ones too), or `--carousel-size` on the carousel for all of them. ```html

``` ## Spacing `--carousel-gap` on the carousel sets the space between items (1rem by default). It is padding on each item, so Embla's snap points stay exact. ```html

``` ## Orientation `data-orientation="vertical"` scrolls up and down (Embla's `axis: "y"`); give the viewport a height. The buttons move above and below and turn, and `↑` `↓` scroll. ```html

``` ## Options `data-carousel-options` takes [Embla's options](https://www.embla-carousel.com/api/options/) as JSON and passes them on: `loop`, `align`, `dragFree`, `slidesToScroll`, `startIndex`, `breakpoints` and the rest. Below: a loop that starts on the third slide. `.carousel-controls` puts the buttons in a row underneath, with an empty `[data-carousel-dots]` that fills with a dot per snap point. ```html

``` ## Plugins Register an Embla plugin under a name once, in your entry script, then ask for it by that name with its options in `data-carousel-plugins`: ```ts app.ts import Autoplay from "embla-carousel-autoplay"; import { initComponents, registerCarouselPlugin } from "htmx-ui"; registerCarouselPlugin("autoplay", Autoplay); // before initComponents() ``` ```html

``` ## API For anything else, take [Embla's API](https://www.embla-carousel.com/api/) from the element once it has loaded: ```ts import { getCarousel } from "htmx-ui"; const el = document.querySelector("#gallery")!; el.addEventListener("carousel:init", (e) => { const api = (e as CustomEvent).detail.api; // same as getCarousel(el) api.scrollTo(3); }); el.addEventListener("carousel:select", (e) => console.log("slide", (e as CustomEvent).detail.index)); ``` ## With htmx A carousel swapped in by htmx initialises like any component. To add slides to one already running, swap them into its `.carousel-container`: Embla notices new slides and re-measures, and the dots and labels follow. ## Reference | Class | Description | | --- | --- | | `.carousel` | The carousel; sets --carousel-gap (1rem) and --carousel-size (100%). | | `.carousel-viewport` | Clips the slides; give it a height when vertical. | | `.carousel-container` | The moving row (column when vertical). | | `.carousel-item` | A slide; basis-* utilities set its size. | | `.carousel-prev / .carousel-next` | Buttons beside the slides (above and below when vertical). | | `.carousel-controls` | A row under the slides for buttons and dots. | | `.carousel-dots / .carousel-dot` | Dot buttons, built in an empty [data-carousel-dots]. | | `[data-carousel]` | Behaviour: starts Embla, buttons, dots, keys, labels. | | `[data-orientation="vertical"]` | Scroll vertically (axis "y"). | | `[data-carousel-options]` | Embla options as JSON. | | `[data-carousel-plugins]` | Plugins by registered name, with their options, as JSON. | | `registerCarouselPlugin(name, factory)` | Make an Embla plugin available by name. | | `getCarousel(el)` | The Embla API of a carousel (after carousel:init). | | `carousel:init / carousel:select` | Events: ready (detail.api), slide changed (detail.index). | --- title: "Collapsible" description: "A button that expands and collapses a panel: more details, extra settings, or a whole file tree." url: "/docs/components/collapsible" section: "Components" --- # Collapsible A button that expands and collapses a panel: more details, extra settings, or a whole file tree. ```html

Order #4189

Status Shipped

``` ## Markup - Wrap everything in `.collapsible` with `data-collapsible`. - The trigger is a ` ``` ## File tree Collapsibles nest: each trigger only opens its own panel. Here every folder is one, with a chevron-right turned by `[--collapsible-rotate:90deg]` on the tree and the folder icon swapped while open. ```html

- - button.ts
  - dialog.ts
- - dom.ts
- index.ts
- favicon.svg
package.json
README.md

``` ## Without JavaScript The same classes style a native `

`: the `

` is the trigger and the icon turns while it's open, with no behaviour at all. The trade-off is that the summary must come first, so the trigger can't sit below the panel. ```html

What does it cost?

Nothing: htmx-ui is MIT licensed.

``` ## Find in page Closed content is invisible to the browser's find-in-page. Close it with `hidden="until-found"` instead of `hidden`, and searching for text inside opens the collapsible; it closes back to `until-found`. Browsers without support treat it as plain `hidden`. ## With htmx Every open and close fires a bubbling `collapsible:toggle` with `detail.open`, and the wrapper carries `data-open` while open. To fetch the panel's content the first time it opens, put the request on the trigger: ```html

``` ## Reference | Class / attribute | Description | | --- | --- | | `.collapsible` | Wrapper (a flex column). Add data-collapsible, or use it on a

. | | `.collapsible-trigger` | A full-width row button, or a

. Optional: any button works. | | `.collapsible-icon` | Turns by --collapsible-rotate (180deg) while open. | | `.collapsible-content` | The panel. Add data-collapsible-content, and hidden to start closed. | | `[data-collapsible-trigger]` | Toggles the panel; aria-expanded and aria-controls kept in sync. | | `[data-open]` | On the wrapper while open. | | `collapsible:toggle` | Event on the wrapper with detail { open }. | --- title: "Separator" description: "A line that visually or semantically separates content: horizontal or vertical." url: "/docs/components/separator" section: "Components" --- # Separator A line that visually or semantically separates content: horizontal or vertical. ```html

htmx-ui

Components for htmx, in plain HTML and CSS.

Docs

Components

Changelog

``` ## Markup - A `.separator` is a one-pixel line in the border colour, as wide as its container. Space it with margin utilities (`my-4`). - `role="separator"` marks a real change of section for screen readers. A line that is only decoration takes `role="none"`, so it isn't announced. An `

` is a separator already. - Content changes for many reasons; a separator is for a break between groups, not between every pair of items. Spacing alone is often enough. ## Orientation `aria-orientation="vertical"` turns the line upright, for a separator between items in a row. It takes the height of its flex row, so the row sets it (`h-5` above); outside a flex row give the separator a height of its own. A decorative vertical line, with `role="none"` and no `aria-orientation`, takes `.separator-vertical` instead. ```html

Blog Docs Source

``` ## Between menu items Vertical separators between items that each carry a description: a separator per gap, stretching to the tallest item. ```html

Settings Manage preferences

Account Profile and security

Help Support and docs

``` ## Between list items Horizontal separators between the rows of a list. The line is decorative here (the list already groups its items), so it is hidden from screen readers. ```html

Item 1: Value 1
Item 2: Value 2
Item 3: Value 3

``` ## With text For a line with a word in it — "Or" between two ways of signing in — use [`.field-separator`](https://susonwaiba.github.io/htmx-ui/docs/components/field#separator). ## Reference | Class / attribute | Description | | --- | --- | | `.separator` | A horizontal line, as wide as its container. | | `[aria-orientation="vertical"]` | On a .separator with role="separator": an upright line, as tall as its flex row. | | `.separator-vertical` | An upright line without aria-orientation, for decorative separators (role="none"). | --- title: "Avatar" description: "An image element with a fallback for representing the user." url: "/docs/components/avatar" section: "Components" --- # Avatar An image element with a fallback for representing the user. ```html

``` ## Image and fallback `.avatar` holds an `.avatar-image` on top of an `.avatar-fallback`, usually initials or an icon. The fallback shows while the image loads, when there is no image, and when it fails to load: the avatar behaviour hides an image that errors, so the fallback shows instead of a broken-image icon. It runs on avatars in fragments from the server too. Name the person once, on the avatar: `role="img"` and `aria-label` on `.avatar`, `alt=""` on the image and `aria-hidden="true"` on the fallback. Next to the visible name, the avatar is decorative: drop the role and label and give it `aria-hidden="true"`. ```html

``` ## Sizes `.avatar-sm` (1.5rem), the default (2rem), `.avatar-lg` (2.5rem) and `.avatar-xl` (3.5rem). The fallback text and badge scale with them; any `size-*` utility works too. ```html

``` ## Badge `.avatar-badge` adds a dot at the bottom right, ringed in the page colour. It is `bg-primary`; colour it with any `bg-*` utility for a status. A dot means nothing to a screen reader, so say the status in the avatar's label. ```html

``` ### Badge with an icon An icon inside the badge makes it big enough to read. ```html

``` ## Group `.avatar-group` overlaps avatars in a row and rings each one in the page colour. Give it `role="group"` and a label. ```html

``` ### With a count `.avatar-group-count` on an `.avatar` ends the group with the number of people not shown. It takes the avatar size classes. ```html

+12

``` ### With an icon An icon in the count, on a button, makes an action at the end of the group, such as inviting someone. ```html

``` ## As a menu trigger An avatar can be the button itself, here opening a [dropdown](https://susonwaiba.github.io/htmx-ui/docs/components/dropdown) of account actions. `.avatar` on a ` ``` ## Reference | Class | Description | | --- | --- | | `.avatar` | Round frame, 2rem. On a button or link: pointer and focus ring. | | `.avatar-image` | The picture, covering the fallback. Give it alt="". Hidden if it fails to load. | | `.avatar-fallback` | Initials or an icon underneath; shows when there is no image or it fails. | | `.avatar-sm / -lg / -xl` | 1.5rem, 2.5rem, 3.5rem; fallback text and badge scale. | | `.avatar-square` | Rounded square instead of a circle. | | `.avatar-badge` | Bottom-right dot (bg-primary; colour with bg-*). Bigger with an icon inside. | | `.avatar-group` | Overlapping row, each avatar ringed in the page colour. | | `.avatar-group-count` | On an .avatar: "+3" or an icon at the end of a group. | --- title: "Item" description: "Displays a row of content with media, a title, a description and actions, alone or in a list." url: "/docs/components/item" section: "Components" --- # Item Displays a row of content with media, a title, a description and actions, alone or in a list. ```html

Basic item

A simple item with a title and a description.

Your profile has been verified.

``` ## Markup An item is a flex row. Every part is optional except the content: ```html

…

``` - `.item-media` sits at the start. Next to a title and a description it aligns with the title rather than the middle. - `.item-content` takes the free space. A second `.item-content` (a date, an amount) only takes the room it needs. - `.item-description` is clamped to two lines. Links inside it are underlined. - `.item-actions` sits at the end. - `.item-header` and `.item-footer` take a full line each, above and below the rest. Items wrap. When the media, the content and the actions don't fit side by side, the actions move to a line of their own, still at the end, so an item works on a phone with no extra classes. ## Variants The default item has no border or background, for lists inside a card or a panel. `.item-outline` adds a border and `.item-muted` a muted background. ```html

Default

Transparent, with no border.

Outline

A border around the item.

Muted

A muted background, for secondary content.

``` ## Sizes The default size, `.item-sm` and `.item-xs` reduce the padding and gaps. The extra small size also shrinks icon and image media and the description. ```html

Inbox

12 unread messages

Inbox

12 unread messages

Inbox

12 unread messages

``` ## Icon `.item-media-icon` puts an icon in a small bordered, muted square. A bare icon in `.item-media` works too. ```html

Security alert

New sign-in from an unknown device in Lisbon, Portugal.

``` ## Avatar Put an [avatar](https://susonwaiba.github.io/htmx-ui/docs/components/avatar) or an avatar group in `.item-media`. The person's name is in the title, so the avatar is decorative: `aria-hidden="true"`, with no role or label. ```html

Ana Lima

Last seen 5 months ago

No team members

Invite your team to collaborate on this project.

``` ## Image `.item-media-image` crops an image to a rounded square: put an `` inside it, or use it on the `` itself. Images next to a title are decorative: `alt=""`. ```html

Mountain Echoes · The Ridgeline

High Country

3:42

Low Tide · Harbour Lights

Saltwater

4:15

Under the Canopy · Moss & Fern

Evergreen

5:03

``` ## Group `.item-group` stacks items in a list. Give it `role="list"` and each item `role="listitem"` (or use a `

`). Put an a [`.separator`](https://susonwaiba.github.io/htmx-ui/docs/components/separator) between items for a line, hidden from screen readers with `aria-hidden="true"` so the list only holds items; or space them with a `gap-*` utility. ```html

Ana Lima

ana@example.com

Kofi Mensah

kofi@example.com

Ravi Patel

ravi@example.com

``` ## Header `.item-header` is a full-width row above the media and content. An image or video directly inside it fills the width with rounded corners; set its shape with an `aspect-*` utility. Laid out in a grid, such items make a set of cards. `.item-footer` is the same below. ```html

Summit-1

Everyday tasks, fast and inexpensive.

Available

Tide-2

Long documents and careful reasoning.

Available

Canopy-3

Images and charts alongside text.

Available

``` ## Link When the whole item goes somewhere and has nothing else to click, make the item the link: ``. It gets a hover background and a focus outline. The same works on a ` ``` ## Dropdown Items work as entries in a [dropdown](https://susonwaiba.github.io/htmx-ui/docs/components/dropdown) menu: give each one `role="menuitem"`. Inside `.dropdown-menu` they take the menu's padding and highlight, and the description shrinks to one line. Use ` ``` ### A menu in the actions Put a dropdown in `.item-actions` for the actions that don't fit as buttons. Align its menu to the end with `.dropdown-menu-end`. ```html

Project Atlas

8 members · Updated yesterday

``` ## Actions with htmx Actions are ordinary buttons, so they take `hx-*` attributes. Here the button posts a setting and the server's reply replaces the status in the description. A server can just as well return whole items, to append to an `.item-group` or to replace one item with `hx-swap="outerHTML"`. ```html

Email notifications

Off. Turn them on to hear about new comments.

``` ## Accessibility - Group items with `role="list"` and `role="listitem"`, or `

`. Don't put `role="listitem"` on an ``: it replaces the link role. Wrap the link in an element with the role instead. - Separators inside a list get `aria-hidden="true"`, so the list holds only items; outside a list, use `role="separator"`. - Never nest a link or button inside ``. For a link item with actions, use `.item-link` on a link around the title. - Icon-only actions need an `aria-label` that names the item: “Invite Ana Lima”, not “Invite”. - Media next to a title is decorative: `alt=""` on images, `aria-hidden="true"` on avatars. - The title is a `

` here. Make it a heading when the items are sections of the page someone would navigate by. ## Reference | Class | Description | | --- | --- | | `.item` | A flex row of media, content and actions that wraps on narrow widths. On an or ``` ## Reference | Class | Description | | --- | --- | | `.table-wrap` | Bordered, rounded, horizontally scrollable wrapper. | | `.table` | Base table styles: header row, cell padding, row dividers. | | `.table-hover` | Highlights the row under the pointer. | --- title: "Timeline" description: "A list of events in chronological order along a line: dots, icons or avatars, colours and sizes, vertical or horizontal, on one side or alternating." url: "/docs/components/timeline" section: "Components" --- # Timeline A list of events in chronological order along a line: dots, icons or avatars, colours and sizes, vertical or horizontal, on one side or alternating. ```html

Recent invoices
Invoice	Status	Method	Amount
INV-001	Paid	Credit card	$250.00
INV-002	Pending	Bank transfer	$150.00
INV-003	Overdue	Credit card	$350.00
INV-004	Paid	PayPal	$450.00

Invoice	Status	Amount
INV-001	Paid	$250.00

7 October 2026

Version 1.0 released

Stable APIs for every component, the engine and the plugins.

14 August 2026

Release candidate

Feature freeze, and a public call for testing.

2 May 2026

First public beta

Forty components and the docs site.

``` ## Markup - An `

` of `

`: a list in order, which is what screen readers announce. It is CSS only, with no behaviour. - Each item has a `.timeline-marker` and a `.timeline-content`. Inside the content, `.timeline-time` (a `
`), `.timeline-title` and `.timeline-description` are all optional; any other markup works too. - The line to the next item is drawn for you, and stops at the last item. - Newest first or oldest first is up to you: the timeline shows items in the order they are written. ## Markers An empty `.timeline-marker` is a dot. `.timeline-marker-primary`, `-success`, `-warning`, `-danger` and `-info` colour it, and `.timeline-marker-outline` makes it hollow. ```html
1. Default
2. Primary
3. Success
4. Warning
5. Danger
6. Info
1. Default
2. Primary
3. Success
4. Warning
5. Danger
6. Info
``` Put an icon, a number or an image in the marker and it becomes a circle; the line and the first line of text centre on it. Plain circles have a border; the colours fill them, and `.timeline-marker-outline` draws a coloured ring instead. ```html
1. Pull request merged
  
  feat(ui): timeline component
2. 3 commits pushed
  
  Alternating layout, sizes and docs.
3. Review requested from Sam
  Yesterday at 4:20 pm
4. Comment
  
  "Looks good: could the dots line up with the first line of text?"
``` ## Progress and the current step For a process (an order, a deployment, an application), colour the steps that are done, mark the current item with `aria-current="step"`, which adds a ring and tells screen readers where it is, and leave the rest as outline markers. Numbers work as markers too. ```html
1. Order placed
  3 Oct, 9:12 am
2. Packed
  4 Oct, 2:40 pm
3. Out for delivery
  
  Arriving today between 1 and 3 pm.
4. Delivered
1. 1
  Create an account
  Done
2. 2
  Verify your email
  Check your inbox
3. 3
  Invite your team
``` ## Rich content The content takes any markup: a [card](https://susonwaiba.github.io/htmx-ui/docs/components/card), an [alert](https://susonwaiba.github.io/htmx-ui/docs/components/alert), buttons. ```html
1. Deploy failed
  10:05 am
  
  Build step exited with code 1
  
  Cannot find module "htmx-ui/timeline". View logs
2. Deploy started
  10:03 am
  
  main · 02e12f4
  
  docs: 0.2.0 changelog and contributor guides
``` ## Opposite content A `.timeline-opposite` in every item goes on the other side of the line, right-aligned in a column `--timeline-opposite` wide (6rem): dates, times or amounts that read down one edge. ```html
1. Keynote
  Main hall
  9:00 am
2. Building with htmx 4
  Room 2
  10:30 am
3. Lunch
  12:00 pm
``` ## Alternating `.timeline-alternate` puts the line in the middle and the items on either side of it in turn, with the `.timeline-opposite`, if any, across from each one. On narrow screens (below the `sm` breakpoint) it falls back to one side, so nothing gets squeezed. ```html
1. Idea
  
  A component library for htmx with no React and no build step for users.
  
  November 2025
2. First components
  
  Buttons, inputs, dialogs and tabs, styled with Tailwind v4.
  
  January 2026
3. Docs site
  
  Built with its own engine, with search and versioned docs.
  
  April 2026
4. Version 1.0
  
  Stable, with a scaffolder for bun, npm, pnpm and yarn.
  
  October 2026
``` ## Horizontal `.timeline-horizontal` lays the items out in a row, each at least `--timeline-min` (10rem) wide, scrolling sideways when they don't fit. A `.timeline-opposite` goes above the line. ```html
1. Plan
  Scope and estimates
  Week 1
2. Design
  Mockups signed off
  Week 2
3. Build
  In progress
  Weeks 3–5
4. Launch
  Week 6
``` With `.timeline-alternate`, horizontal items go above and below the line in turn. The markers stay in one row whatever sits above them. ```html
1. Jan
  Kick-off
2. Mar
  Alpha
  Internal testing
3. May
  Beta
4. Aug
  Release candidate
  Feature freeze
5. Oct
  1.0
``` ## Line style `.timeline-dashed` and `.timeline-dotted` change the line, vertical or horizontal. ```html
1. Dashed
2. Second
3. Third
1. Dotted
2. Second
3. Third
``` ## Sizes `.timeline-sm` and `.timeline-lg` scale the markers, the text and the spacing together. ```html
1. Small
  Signed up
2. Email sent
  Welcome
3. Profile
  Completed
1. Default
  Signed up
2. Email sent
  Welcome
3. Profile
  Completed
1. Large
  Signed up
2. Email sent
  Welcome
3. Profile
  Completed
``` ## With htmx A timeline is a list, so loading more events is appending items. Here a button at the end fetches the next page and replaces itself with it (`hx-swap="outerHTML"`), the response being more `

`s and a new button: ```html activity.html

``` ## Customising Every measurement is a custom property on `.timeline`; set them with Tailwind's arbitrary properties or your own CSS. | Property | Description | | --- | --- | | `--timeline-dot` | Dot size (0.75rem). | | `--timeline-icon` | Circle size for icon, text and image markers (2rem). | | `--timeline-line` | Line thickness (2px). | | `--timeline-gap` | Between the marker and the content (0.75rem). | | `--timeline-space` | Between items (1.5rem). | | `--timeline-opposite` | Width of the .timeline-opposite column, vertical (6rem). | | `--timeline-min` | Narrowest item, horizontal (10rem). | ## Reference | Class / attribute | Description | | --- | --- | | `.timeline` | The list: an

. aria-current="step" rings its marker. | | `.timeline-marker` | Empty: a dot. With an icon, text or image: a circle. | | `.timeline-marker-primary / -success / -warning / -danger / -info` | Marker colours. | | `.timeline-marker-outline` | A hollow marker, in its colour. | | `.timeline-content` | The event: .timeline-time, .timeline-title, .timeline-description, or anything. | | `.timeline-opposite` | Across the line from the content. | | `.timeline-alternate` | Items on both sides of the line in turn. | | `.timeline-horizontal` | Items in a row. | | `.timeline-dashed / .timeline-dotted` | Line style. | | `.timeline-sm / .timeline-lg` | Sizes. | --- title: "Code block" description: "Syntax-highlighted source with a copy button, file tabs, and package-manager tabs that remember the reader's choice. Every snippet in these docs uses it." url: "/docs/components/code-block" section: "Components" --- # Code block Syntax-highlighted source with a copy button, file tabs, and package-manager tabs that remember the reader's choice. Every snippet in these docs uses it. ```ts src/app.ts import { initComponents } from "htmx-ui"; // Wire up components inside content htmx inserts document.addEventListener("htmx:after:process", (e) => { initComponents((e.target as ParentNode) ?? document); }); ``` ## Syntax highlighting Code is highlighted **at build time** by [Shiki](https://shiki.style), so pages ship coloured HTML and no highlighting JavaScript. Supported languages: `html`, `css`, `ts`/`js`, `json`, `bash`, `toml`, `md`, `xml`/`svg` and `jinja` (Nunjucks). Anything else is shown escaped, uncoloured. Colours are CSS variables, `--code-token-keyword`, `--code-token-string` and so on, defined for light and dark next to the other [tokens](https://susonwaiba.github.io/htmx-ui/docs/theming). Override them to restyle every code block. ```css src/styles.css :root { --code-token-keyword: var(--color-fuchsia-600); --code-token-string: var(--color-teal-700); } ``` ## Package-manager commands Install commands come in bun, npm, pnpm and yarn flavours. Switch tabs here and every command block on every page follows. The choice is saved in `localStorage` and restored on your next visit. ```bash bun bun add htmx-ui htmx.org bun add -d tailwindcss ``` ```bash npm npm install htmx-ui htmx.org npm install -D tailwindcss ``` ```bash pnpm pnpm add htmx-ui htmx.org pnpm add -D tailwindcss ``` ```bash yarn yarn add htmx-ui htmx.org yarn add -D tailwindcss ``` With the Nunjucks macro, write each line with an action and it's translated for each manager: ```jinja page.html {% from "components/code/code.html" import cli %} {{ cli("add htmx-ui htmx.org add-dev tailwindcss run dev") }} ``` | Action | Description | | --- | --- | | `init` | npm init -y · pnpm init · yarn init -y · bun init -y | | `install` | npm install · pnpm install · yarn install · bun install | | `add` | npm install · pnpm add · yarn add · bun add | | `add-dev` | npm install -D · pnpm add -D · yarn add -D · bun add -d | | `run` | npm run · pnpm run · yarn run · bun run | | `exec` | npx · pnpm dlx · yarn dlx · bunx | | `create` | npm create · pnpm create · yarn create · bun create | | `anything else` | Shown unchanged on every tab, e.g. mkdir my-app && cd my-app | The commands live in `htmx-ui/components/code/package-managers.json`; add a manager or change the default there. ## File tabs Show related files side by side: ```html index.html ``` ```css styles.css @layer components { .btn { @apply font-semibold; } } ``` ## Markup The copy button is an icon-only [clipboard](https://susonwaiba.github.io/htmx-ui/docs/components/clipboard) button with `data-clipboard-target="pre:not([hidden]) code"`: the clipboard copies the nearest match, which is the visible `

` in its own block, and shows a green tick for two seconds. `.code-copy` mutes it until hovered; without a header it floats over the top-right corner of the code.

``` app.ts
initComponents(document);
```

For tabs, put `data-tabs` on the block (plus `data-tabs-sync="key"` to sync), `.tabs-trigger` buttons with `data-tab` in a `.tabs-list.tabs-line.code-tabs` strip in the header (underlined tabs, fitted to it), and one `` per tab. See [Tabs](https://susonwaiba.github.io/htmx-ui/docs/components/tabs).

## Nunjucks macros

```jinja page.html
{% from "components/code/code.html" import code, code_block, code_tabs, cli %}

{% call code("html", title="index.html") %}
  
{% endcall %}

{{ code_block(some_string, "ts") }}
{{ code_tabs([{ id: "a", label: "a.ts", lang: "ts", source: a }], sync="files") }}
```

Bodies are de-indented and escaped. Wrap Nunjucks syntax in `{% raw %}` so it's shown, not run.

## Reference

| Class | Description |
| --- | --- |
| `.code-block` | Container: border, code background and the  inside. |
| `.code-block-header` | Top bar for a file name, tabs and the copy button. |
| `.code-copy` | On the copy button (an icon-only .clipboard): muted until hovered. |
| `.code-tabs` | On a .tabs-list.tabs-line of .tabs-trigger buttons: the tab strip, fitted to the header. |
| `data-clipboard-target="pre:not([hidden]) code"` | On the copy button: copies the visible  of its block. |
| `--code-background / --code-foreground / --code-token-*` | Highlighting colours (CSS variables). |


---
title: "Icon"
description: "SVG icons stored as files in htmx-ui/icons and inlined into the HTML at build time, so they inherit colour and need no requests. They can also be linked as images."
url: "/docs/components/icon"
section: "Components"
---

# Icon

SVG icons stored as files in htmx-ui/icons and inlined into the HTML at build time, so they inherit colour and need no requests. They can also be linked as images.

```html




```

## Usage

Icons are 24×24 Lucide-style SVGs drawn with `stroke="currentColor"`, so they take the text colour. Size them with Tailwind (`size-4`, `size-5`…). The macro inlines the file's ` pointing at a copy of the file #}
```

## Inline or image

|  | Inline (default) | `mode="img"` |
| --- | --- | --- |
| Colour | Inherits text colour (`text-primary` works) | Fixed black stroke; the macro adds `dark:invert` |
| Requests | None, part of the HTML | One per icon; the file is content-hashed, so it caches forever |
| Use when | Almost always | Many repeats of a large SVG, or linking from elsewhere |

```html


```

In `img` mode the bundler copies the SVG next to the page with a content hash in its name (`sun-a1b2c3.svg`), so a changed icon is never served stale.

Separately, this site's build copies the package's `icons/` to `dist/assets/icons/` with **unchanged** names. `/assets/icons/.svg` is therefore a stable URL for linking from other sites, emails or docs, e.g. [/assets/icons/sun.svg](https://susonwaiba.github.io/htmx-ui/assets/icons/sun.svg).

## Any SVG

The `svg()` template function inlines any SVG file under a template root (your project, then htmx-ui), setting or overriding attributes on its root element:

```jinja
{{ svg("images/logo.svg", { class: "h-8 w-auto", "aria-label": "HTMX UI", role: "img" }) }}
```

## Adding an icon

1. Save a 24×24 SVG with `stroke="currentColor"` (or `fill="currentColor"`) as `icons/.svg` in your project; your file wins over a package icon of the same name. [Lucide](https://lucide.dev) icons drop straight in.
2. Use it: `{{ icon("") }}`. A misspelt name fails the build.

## All icons

94 icons, listed straight from the package's `icons/` with `glob()`:

Icon names: alert-triangle, align-center, align-left, align-right, arrow-down, arrow-left, arrow-right, arrow-up-right, arrow-up, asterisk, badge-check, bar-chart, bell, bold, book, bookmark, bot, box, calendar, check-circle, check, chevron-down, chevron-left, chevron-right, chevron-up, chevrons-left, chevrons-right, chevrons-up-down, circle-alert, circle, cloud, code, command, copy, corner-down-left, credit-card, download, ellipsis-vertical, ellipsis, external-link, eye-off, eye, file-text, file, folder-open, folder-plus, folder, git-commit, history, house, image, inbox, info, italic, layers, link, loader-spokes, loader, log-in, log-out, mail, menu, message-square, minus, monitor, moon, music, palette, panel-left, panel-right, paperclip, play, plus, refresh-cw, search, send, server, settings, shield-check, slash, sparkles, star, sun, terminal, trash, truck, underline, upload, user, users, video, x-circle, x, zap

## Reference

| Macro / function | Description |
| --- | --- |
| `icon(name, class="size-4")` | Inline icons/.svg with a class. aria-hidden by default. |
| `icon(name, label="…")` | Meaningful icon: role="img" and aria-label instead of aria-hidden. |
| `icon(name, mode="img")` |  of a hashed copy of the file instead of inlining. |
| `svg(path, attrs)` | Inline any SVG under a template root, setting attributes on the root +
  B

```

## Markup

- A key is a ``. It holds text (`Esc`, `K`, `↵`) or an [icon](https://susonwaiba.github.io/htmx-ui/docs/components/icon), which is sized to the key.
- A shortcut of several keys is a `.kbd-group` around them, with any text between: `+`, `then`. Make the group a `` too, as HTML nests `` for a key combination.
- Give an icon key a name for screen readers when the symbol alone could be misread: `icon("command", label="Command")`.
- Inside `.prose`, a bare `` is already styled by the [text](https://susonwaiba.github.io/htmx-ui/docs/components/text) styles; use `.kbd` in UI.

## Group

Keys in a sentence: `.kbd-group` keeps a shortcut together and spaces its keys evenly.

```html

  Use
  Ctrl+B
  or
  Ctrl+K
  to open the command palette.

```

## Button

A key at the end of a [button](https://susonwaiba.github.io/htmx-ui/docs/components/button) shows its shortcut. On filled buttons it becomes a translucent chip of the button's text colour; in small buttons it shrinks with them.

```html




```

## Tooltip

In a [tooltip](https://susonwaiba.github.io/htmx-ui/docs/components/tooltip) the key inverts with it, so it reads in both themes.

```html

  
    
    Save changes S
  
  
    
    Print document CtrlP
  

```

## Input group

A key in an [input group](https://susonwaiba.github.io/htmx-ui/docs/components/input-group) addon hints at the shortcut that focuses the field, like the search box at the top of this page.

```html

  
  
  
    K
  

```

## Reference

| Class | Description |
| --- | --- |
| `.kbd` | One key: text or an icon. |
| `.kbd-group` | Keys of one shortcut, with optional text between them. |


---
title: "Text"
description: "Style long-form content without a class on every element: wrap it in .prose from @tailwindcss/typography, tuned to htmx-ui's tokens. Small helper classes cover single elements in UI chrome."
url: "/docs/components/text"
section: "Components"
---

# Text

Style long-form content without a class on every element: wrap it in .prose from @tailwindcss/typography, tuned to htmx-ui's tokens. Small helper classes cover single elements in UI chrome.

## Prose

Wrap plain HTML (an article, Markdown output, CMS content, a server-rendered fragment) in `.prose`. Every heading, paragraph, list, link, quote, table and code element inside is styled. No per-element classes.

```html

  Shipping hypermedia
  Your server already renders HTML. htmx swaps it in; htmx-ui makes it look good.
  Return a fragment from any endpoint, point hx-target at it, and you're done. See installation.
  
    Plain HTML in, styled content out
    Works with Markdown renderers and CMS output
  
  Hypermedia is the engine of application state.
  Press Ctrl + K to search.

```

`.prose` comes from [@tailwindcss/typography](https://github.com/tailwindlabs/tailwindcss-typography), which `htmx-ui/styles.css` loads for you. Everything in its docs works: sizes (`prose-sm`, `prose-lg`), element modifiers (`prose-a:text-primary`, `prose-headings:tracking-tight`), and `max-w-none` to drop the default line-length limit.

## What htmx-ui changes

- **Colours come from the [tokens](https://susonwaiba.github.io/htmx-ui/docs/theming)**: body and headings use `--foreground`, links `--primary`, rules and table borders `--border`, code blocks `--code-background`. Prose therefore follows custom themes and dark mode on its own. **Don't add `dark:prose-invert`.**
- Inline `code` is a pill on a muted background instead of being wrapped in backticks.
- Links get a soft underline that firms up on hover.
- Headings get `scroll-margin-top` so `#anchor` links clear a sticky header.
- Components placed inside prose with `not-prose` (alerts, code blocks, tables) get the same vertical spacing as paragraphs.

## Components inside prose

Prose styles every element inside it, which would also restyle a component's markup. Add `not-prose` to a component to keep its own styles. htmx-ui's Nunjucks macros (`code`, `alert`) already do. The flip side: `.prose` placed _inside_ a `not-prose` element gets no styles at all, so don't nest them that way.

```html

  Before you deploy:

  
    Back up your database
  

  Then run the migration.

```

## Sizes

```html
prose-sm: for sidebars, cards and dense UIs.
prose: the default, for articles and docs.
prose-lg: for landing-page copy.
```

## Customising further

Tweak one block with element modifiers, or change prose everywhere by adding to the `prose` utility:

```html
…
```

```css src/styles.css
@utility prose {
  --tw-prose-bullets: var(--primary);

  & :where(h2):not(:where([class~="not-prose"] *)) {
    border-bottom: 1px solid var(--border);
    padding-bottom: 0.5rem;
  }
}
```

## Single elements

UI chrome (a page title, a hint under a form field) isn't long-form content. For one-off elements outside prose, use these helpers:

```html
Settings
Account
Manage your profile and preferences.
Danger zone
Deleting your account can't be undone.
Read the theming guide, run bun run dev, press Esc.
```

> **Which one?** More than a couple of text elements in a row is content: use `.prose`. A single label or title in a layout: use a helper.

## Reference

| Class | Description |
| --- | --- |
| `.prose` | Long-form content (@tailwindcss/typography), mapped to htmx-ui tokens. |
| `.prose-sm / .prose-lg` | Smaller / larger prose. |
| `.not-prose` | Opt a subtree (usually a component) out of prose styles. |
| `.h1 / .h2 / .h3 / .h4` | Heading scale for single titles outside prose. |
| `.lead` | Intro paragraph: larger, muted. |
| `.muted` | Small secondary text. |
| `.eyebrow` | Small primary-coloured label above a heading. |
| `.link` | Underlined link in the primary colour. |
| `.code` | Inline code outside prose. |
| `.kbd` | Keyboard key outside prose; see Kbd for groups and keys in buttons and tooltips. |


---
title: "Attachment"
description: "Displays a file or image attachment with media, metadata, upload state and actions."
url: "/docs/components/attachment"
section: "Components"
---

# Attachment

Displays a file or image attachment with media, metadata, upload state and actions.

```html

  
  
    quarterly-report.pdf
    2.4 MB · PDF
  
  
    
  


  
  
    mountains-at-dusk.svg
    Uploading · 64%
  
  
    
  
  

```

## Parts

- `.attachment` is the frame: media, content and actions in a row.
- `.attachment-media` holds an icon, or an image. It can also be the `` or `

Deploy preview

default

rose

emerald

aurora

ember

lagoon

dusk

jade

onyx

{{ title }}

{{ title }}

Log in to your account

Notifications

Weekend in the mountains

Image at the bottom

Alpine route

Terms of service

Small card

All components

Server message

Order #4189

Radius

Version 1.0 released

Release candidate

First public beta

Pull request merged

3 commits pushed

Review requested from Sam

Comment

Order placed

Packed

Out for delivery

Delivered

Create an account

Verify your email

Invite your team

Deploy failed

Deploy started

Keynote

Building with htmx 4

Lunch

Idea

First components

Docs site

Version 1.0

Plan

Design

Build

Launch

Kick-off

Alpha

Beta

Release candidate

1.0

Small

Email sent

Profile

Default

Email sent

Profile

Large

Email sent

Profile

Shipping hypermedia

Account

Danger zone