---
title: "v0.2.0"
description: "Plugins, with docs, versions and search as the first three; named template roots; serving a site from your own backend with five adapters (Elysia, Fastify, Koa, Express, Hono) and a default 404 page; and 37 new components, from dialogs, menus and toasts to an AI chat stack."
url: "https://susonwaiba.github.io/htmx-ui/docs/v0.2/changelog/0.2.0"
section: "Project"
---

# v0.2.0

Plugins, with docs, versions and search as the first three; named template roots; serving a site from your own backend with five adapters (Elysia, Fastify, Koa, Express, Hono) and a default 404 page; and 37 new components, from dialogs, menus and toasts to an AI chat stack.

[All releases](https://susonwaiba.github.io/htmx-ui/docs/v0.2/changelog) Latest 2026-10-06

## Breaking changes

Three changes need an edit in your config, your command line or your sidebar markup.

### templates is now roots

The two options are one, and `roots[0]` is the project root, which `templates` never moved. Rename the key and keep your project directory first unless it already is:

- Before: `defineConfig({ templates: ["."] })`
- After: `defineConfig({ roots: ["."] })`

A config that still says `templates` is a TypeScript error, not a silent fallback. `ResolvedConfig.templateRoots` is gone with it; read `ResolvedConfig.roots` (the same list, entries as `{ name?, dir }`) and map `dir` if you needed the bare directories. See [Roots](https://susonwaiba.github.io/htmx-ui/docs/v0.2/engine#roots).

### create-htmx-ui defaults to bun

The scaffolder's `--pm` default is `bun` instead of `npm`. Pass `--pm npm` (or `pnpm`, `yarn`) for the old behaviour. Since `bun create htmx-ui` already ran Bun, this mostly changes what the scaffolder writes into a new project's `package.json` scripts and lockfile.

### Sidebar is a composable app sidebar

The sidebar is rebuilt from parts: a layout, header, content, groups, menus, footer, rail and trigger, with variants, collapsible modes and a mobile panel. Rename the old classes:

- `.sidebar-link` becomes `.sidebar-menu-button`, in a `<li class="sidebar-menu-item">` of a `<ul class="sidebar-menu">`.
- `.sidebar-label` becomes `.sidebar-group-label`.
- `.sidebar-backdrop` is gone: wrap the sidebar and its main area in `.sidebar-layout`, which draws the backdrop.
- `[data-sidebar-toggle]` becomes `[data-sidebar-trigger]`; `[data-sidebar-close]` is now for close buttons inside the panel.

For the old sticky column from `lg`, set `data-collapsible="none" data-breakpoint="lg"`, `--sidebar-top: 3.5rem` and `--sidebar-width: 15rem`. See [Sidebar](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/sidebar) for the full upgrade table.

## Added

### Components

37 new components, each with a docs page of its own. The [components index](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components) now groups every component by category (forms, actions, navigation, overlays, feedback, layout, data, content and chat), so the sidebar, prev/next links and the agent outputs follow the same order.

- [Checkbox](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/checkbox): a native checkbox styled with the design tokens, in sizes, with disabled, invalid and indeterminate states.
- [Radio group](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/radio-group): native radios as cards or inline rows, so a choice is one control that submits with the form.
- [Select](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/select): a listbox in a popup opened from a button, styled like an input, searchable and keyboard driven, falling back to the native `<select>` without JavaScript.
- [Switch](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/switch): an on/off setting that applies at once, drawn as a sliding track on a real checkbox, so it needs no JavaScript.
- [Dialog](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/dialog): a modal on the native `<dialog>`, opened with invoker commands and closed by Escape, a click outside or any `[data-dialog-close]`. Scrolling content, a sticky footer, dialogs over dialogs, and htmx support: a dialog a request returns opens itself, and `HX-Trigger: dialog:close` closes one from the server.
- [Alert dialog](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/alert-dialog): a dialog with `role="alertdialog"` that waits for an answer, with a small size, media and destructive actions.
- [Attachment](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/attachment): files, images, video and audio with upload states (and a shimmer while in progress), three sizes, a vertical orientation and a scrolling, snapping group.
- [Avatar](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/avatar): an image with a fallback, in sizes, with status badges, groups and a count, and as a menu trigger.
- [Breadcrumb](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/breadcrumb): custom separators, dropdowns, an ellipsis, and collapsing on its own when it doesn't fit.
- [Badge](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/badge): ghost and link variants, solid status badges, any colour with `.badge-tone`, and hover and focus styles on badges that are links.
- [Tooltip](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/tooltip): a short hint on hover or keyboard focus, on any side, shown by CSS alone; a small behaviour adds `aria-describedby` and dismissing with `Esc`.
- [Label](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/label): `.label` for any control, around checkboxes, radios and switches, or as a `.label-card` choice card. It works as `.field-label` inside a field.
- [Separator](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/separator): a horizontal or vertical line, semantic or decorative.
- [Collapsible](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/collapsible): a button anywhere inside shows and hides a panel; collapsibles nest into file trees, and the same classes style `<details>` with no JavaScript.
- [Combobox](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/combobox): an input with suggestions that filters as you type (ignoring case, accents and word order, with keywords), groups and separators, auto highlight, multiple picks as chips, a clear button, form states, a macro, and server-side search with htmx.
- [Input OTP](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/input-otp): a one-time code in slots over one real input, so pasting, SMS autofill and the phone's number pad just work; digit, alphanumeric or custom patterns, groups and separators, masking, sizes and states.
- [Kbd](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/kbd): keys and shortcuts with `.kbd` and `.kbd-group`, at home in buttons, tooltips and input groups.
- [Popover](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/popover): a header and footer, explicit start alignment, and `data-popover-close` buttons for forms.
- [Progress](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/progress): a styled native `<progress>` with a label, value and help text, sizes, colours, an indeterminate state and a `progress()` macro.
- [Pagination](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/pagination): page links with previous and next, first and last, icon-only buttons for data tables, a responsive mode, and a `pagination()` macro that works out the page range with ellipses.
- [Item](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/item): media, a title, a description and actions, in variants and sizes, with icons, avatars, images, headers, groups, whole-item links and dropdowns.
- [Empty](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/empty): empty states with an icon or avatars, a message and actions, in outline and muted variants, with an `empty()` macro.
- [Menubar](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/menubar): a persistent row of menus with roving focus, typeahead, submenus, checkbox and radio items, shortcuts and a vertical orientation.
- [Navigation menu](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/navigation-menu): site navigation with links and triggers opening panels, from simple lists to mega menus, with hover delays and arrow keys.
- [Hover card](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/hover-card): a preview of what is behind a link, on hover or keyboard focus, on any side and alignment, flipping at the viewport edge, and lazy-loadable with htmx.
- [Sheet](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/sheet): a dialog attached to any edge of the screen, in sizes, with every dialog feature and a `sheet()` macro.
- [Drawer](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/drawer): a panel you swipe away in any of four directions, with a drag handle, nested drawers that stack behind the frontmost, and a responsive dialog from `md`.
- [Slider](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/slider): one value, a range or several thumbs on native range inputs, vertical too, with form states, sizes, `<output>` values and a `slider()` macro.
- [Skeleton](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/skeleton): placeholders of any shape, text lines, pulse or shimmer, and macros for avatars, cards, lists, tables and forms.
- [Toast](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/toast): stacking, swipeable notifications in five types with actions and promises, from script, markup, the `HX-Trigger` header or any htmx request.
- [Command](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/command): a command menu with filtering, keyboard navigation, groups, shortcuts, a ⌘K dialog and server-side search.
- [Carousel](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/carousel): Embla Carousel, loaded on demand, with item sizes, spacing, a vertical orientation, options and plugins.
- [Message](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/message): chat messages with avatars, headers, footers, alignment, variants, groups and attachments, plus reasoning, tool calls and typing for AI chat.
- [Loader](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/loader): eight pure-CSS loading indicators, from bouncing dots and waves to shimmering text, sized, timed and coloured with custom properties.
- [Scroll button](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/scroll-button): a floating button that appears once the reader scrolls away from an edge, and jumps back to the bottom of a container or the top of the page.
- [Reasoning](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/reasoning): a collapsible for AI reasoning that opens while it streams and closes, with how long it took, when the stream ends.
- [Chain of thought](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/chain-of-thought): steps on a connecting line, each with a status and details that fold away, for reasoning traces, tool calls and logs.
- [Prompt input](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/prompt-input): the text box of an AI chat: a growing textarea, tools, send and stop, and `@` mention and `/` command menus.
- [Message scroller](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/message-scroller): scrolling for a streaming chat transcript: new questions rise to the top, replies grow beneath them, the reader's place survives layout changes and loaded history, and links jump to any message.
- [Textarea](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/textarea): its own page, a character count, keyboard submit, sizes and states.
- [Tabs](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/tabs): vertical tabs, disabled tabs, icons, and pill, outline and full-width styles.
- [Dropdown](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/dropdown): checkbox and radio items, shortcuts, destructive items, submenus, typeahead, a `menu:change` event and form fields for named items.
- [Sidebar](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/sidebar): variants, collapsing to icons with tooltips or off the screen, either side, Ctrl/⌘+B, a rail, a saved state in a cookie, a mobile panel and `--sidebar-*` tokens.

### Templates and data

- [Named template roots](https://susonwaiba.github.io/htmx-ui/docs/v0.2/engine#roots): `roots` in `htmx-ui.config.ts` is an ordered list of directories, each optionally named, and the first entry is the project root. A name is the prefix templates reach that directory by, so it can move without a single template changing.
- Names work everywhere a template name does — `extends`, `include`, `import`, `from`, `json()`, `svg()`, `glob()` and `asset()` — because resolution moved into a loader Nunjucks uses for every template load.
- [Deploying templates](https://susonwaiba.github.io/htmx-ui/docs/v0.2/servers/deploying#static-and-dynamic) a server renders at runtime: copy the roots next to `dist/` and point `roots` at the copy.

### Plugins

- [Plugins](https://susonwaiba.github.io/htmx-ui/docs/v0.2/plugins): optional features as separate packages, listed under `plugins` in `htmx-ui.config.ts`. A plugin can add template roots, globals, filters, a transform, routes, a fetch fallback, files written by the build and CLI commands; the project's own options always win. They work in `htmx-ui dev`, builds, on Bun and Node, and behind every server adapter.
- The first three, which this website's docs now run on: [htmx-ui-plugin-docs](https://susonwaiba.github.io/htmx-ui/docs/v0.2/plugins/docs) (heading anchors, Markdown for every page, llms.txt, sitemaps, `docsNav()` and page macros), [htmx-ui-plugin-versions](https://susonwaiba.github.io/htmx-ui/docs/v0.2/plugins/versions) (archived docs versions, the version switcher and banner, `htmx-ui versions:name` and `htmx-ui versions:archive`) and [htmx-ui-plugin-search](https://susonwaiba.github.io/htmx-ui/docs/v0.2/plugins/search) (the Ctrl/⌘K palette). They release with the other packages, at the same version.
- [Writing a plugin](https://susonwaiba.github.io/htmx-ui/docs/v0.2/plugins/writing): `definePlugin()`, `editHtml()` (a streaming HTML editor for transforms that runs on Bun and Node alike) and `contentType()` from `htmx-ui-engine`, plugin commands listed by `htmx-ui --help`, and an `api` for plugins that build on each other.

### Engine

- [Serving a site from your own backend](https://susonwaiba.github.io/htmx-ui/docs/v0.2/servers): `createSite()` is the framework-free core of the dev servers, wrapped by `htmx-ui-engine/elysia` (recommended), `htmx-ui-engine/fastify`, `htmx-ui-engine/koa`, `htmx-ui-engine/express` and `htmx-ui-engine/hono`. None of them imports its framework. Elysia, Fastify and Koa answer only what your own routes don't, whatever the order; Express and Hono are mounted last. Recipes cover [Bun.serve](https://susonwaiba.github.io/htmx-ui/docs/v0.2/servers/bun), [Deno, node:http, h3 and NestJS](https://susonwaiba.github.io/htmx-ui/docs/v0.2/servers/other), and [backends in other languages](https://susonwaiba.github.io/htmx-ui/docs/v0.2/servers/any-backend).
- `site.render()` renders a full page, `site.fragment()` renders any template as an htmx fragment, and `site.handle()` answers a request from config `routes`, the built `dist/`, the config's `fetch`, then a [404 page](https://susonwaiba.github.io/htmx-ui/docs/v0.2/servers#not-found). Outside production it renders a page from its template when nothing is built yet, with the `context` you pass.
- A default 404 page: a project without `pages/404.html` gets htmx-ui's own, from the adapters, `htmx-ui dev`, `htmx-ui preview` and as `dist/404.html` in every build. Add `pages/404.html` to replace it.
- Request bodies a framework's body parser already read (`express.urlencoded()`, `express.json()`, Fastify's JSON parser, Koa body parsers) reach the config's `routes` intact.
- Code blocks highlight `docker` and `nginx`.
- `render: true` in the config checks at startup that the template roots and pages directory arrived, so a packaging mistake fails the boot instead of the first request.
- A cached runtime renderer: `render(path, roots, { cache: true })` with `warm()` to compile ahead of the first request (`createSite()` does both), and `markup()` for a global that returns HTML.
- `debug` in the config logs what answered each request, every render with its duration, what the template cache compiled, and builds: `debug: true` for everything or a list of topics (`requests`, `render`, `templates`, `build`). Off by default.

### Package

- `htmx-ui` exports the component APIs for script — `toast` and its types, `registerCarouselPlugin`, `getCarousel`, `matchesHotkey`, `commandMatches`, `getMessageScroller`, `scrollToEdge`, `distanceFromEdge` and `scrollTargetOf` — plus `queryAll` (the helper components use to include the root in their scan) and the `Theme` type. It now depends on `embla-carousel` for the carousel.
- `htmx-ui-engine` exports `createSite`, `Site`, `SiteOptions`, `normalizeRoots`, `tryLocate`, `locate`, `TemplateRoot`, `RootSpec`, `warm`, `markup`, `logger`, `TOPICS` and the plugin writer's kit: `definePlugin`, `editHtml` and `contentType`.
- 37 new icons, from `arrow-up` and `bell` to `folder-plus`, `paperclip`, `shield-check` and `users`.
- `bun run version:set <x.y.z>` names the docs version in development, dates it, and sets the version on every package at once.

## Changed

- Components animate with shared [motion tokens](https://susonwaiba.github.io/htmx-ui/docs/v0.2/theming#motion) (`--motion-duration-*`, `--motion-ease-*`), which collapse to `0s` for reduced motion. Popovers, dropdown and menubar menus, select and combobox lists fade and zoom in from their trigger and fade out, in CSS only; dialogs also rise slightly as they open.
- The dev watcher honours `.gitignore` and skips `node_modules`, `dist`, `public` and `.git` whatever the roots say, so a root of `.` no longer adds a file watcher for every directory in `node_modules`. The trade-off: a new file under one of those directories shows up on the next refresh rather than immediately.
- The dev server watches the roots you configured, so a template that moved is still watched.
- Dropdown items no longer spread their content apart: content is left-aligned and trailing badges, shortcuts and icons are pushed right. Hovering an item focuses it, and choosing one returns focus to the trigger.
- `.tabs` is styled: a column with a gap between the list and the panels (side by side when vertical), in place of the margin on `.tabs-panel`.
- `data-dialog-remove` waits for the dialog's own transition before removing it, so sheets and drawers finish sliding out.

## Fixed

- Links in a `.field-description` are underlined again; the minified build dropped the underline.
- `htmx-ui build` on Bun prints the bundler's own errors, such as an import that doesn't resolve, instead of only "Bundle failed".
- Icons in a [badge](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/badge) are badge-sized again; the `size-4` class `icon()` adds used to win over the badge's own icon size.
- `assetVer()`'s `?ver=` can no longer break a build or be dropped by the bundler. Neither Bun nor Vite can resolve an asset URL carrying a query string, so the version is parked in a `data-ver` attribute before the bundler sees the page and moved onto the finished URL after it.
- `.select` no longer restyles the select component's trigger as a native dropdown; the rule is scoped to `select.select`.
- A field whose label sits in `.field-content` — what a switch or a radio group produces — marks an invalid field the same way a top-level label does, instead of losing the danger colour.