`). `.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

. | | `.sidebar-group` | Still the section, now with padding and no margin between groups: wrap the groups in .sidebar-content and set its gap. | | `.sidebar-backdrop` | Remove it: the backdrop is drawn by .sidebar-layout. | | `[data-sidebar-toggle]` | [data-sidebar-trigger]. | | `[data-sidebar-close]` | Same name; now for close buttons, not the backdrop. | | `[data-open]` | Same meaning (the mobile panel is open), but set only in mobile mode. | | `.sidebar (lg sticky column)` | Wrap it with its main area in .sidebar-layout. For the old look: data-collapsible="none" data-breakpoint="lg", --sidebar-top for the header, --sidebar-width: 15rem, and a transparent --sidebar from lg up (see the docs navigation above). | ## Reference | Class | Description | | --- | --- | | `.sidebar-layout` | The layout: a flex row of the sidebar and .sidebar-inset, at least as tall as the window. Draws the mobile backdrop. | | `.sidebar-inset` | The main area beside the sidebar. A raised panel with data-variant="inset". | | `.sidebar` | The sidebar column. Sticky; full height minus --sidebar-top. | | `.sidebar-header` | Top part: logo, workspace or environment switcher, search. | | `.sidebar-content` | Middle part; scrolls. | | `.sidebar-footer` | Bottom part: user menu. | | `.sidebar-separator` | A line between parts or groups. | | `.sidebar-input` | A compact .input for the sidebar. | | `.sidebar-group` | A section of the content. | | `.sidebar-group-label` | Group heading. On a button or summary, a collapsible trigger. | | `.sidebar-group-action` | Icon button in the group's top-right corner. | | `.sidebar-group-content` | Wraps the group's menu (the collapsible content). | | `.sidebar-menu` | A list of items (ul). | | `.sidebar-menu-item` | An item (li). Add .tooltip for an icon-mode tooltip. | | `.sidebar-menu-button` | The item's link or button. Current with aria-current="page" or data-active. | | `.sidebar-menu-button-sm` | 28px tall, smaller text. | | `.sidebar-menu-button-lg` | 48px tall, for two lines or an avatar. | | `.sidebar-menu-button-outline` | With a border and a background. | | `.sidebar-menu-action` | Icon button at the end of an item (or a dropdown trigger there). | | `.sidebar-menu-action-hover` | Shows the action only while the item is hovered or focused. | | `.sidebar-menu-badge` | A count or status at the end of an item. | | `.sidebar-menu-sub` | A nested list under an item. | | `.sidebar-menu-sub-item` | An item of a sub-menu. | | `.sidebar-menu-sub-button` | A sub-menu link. Current with aria-current="page" or data-active. | | `.sidebar-menu-sub-button-sm` | Smaller sub-menu text. | | `.sidebar-menu-skeleton` | A loading placeholder item. | | `.sidebar-menu-skeleton-icon` | Its icon square. | | `.sidebar-menu-skeleton-text` | Its text bar; width from --skeleton-width (70%). | | `.sidebar-trigger` | A small icon button for data-sidebar-trigger. | | `.sidebar-rail` | Thin toggle strip along the inner edge (with data-sidebar-rail). | | `data-sidebar` | Behaviour: marks the sidebar. | | `data-side` | left (default) or right. | | `data-variant` | sidebar (default), floating or inset. | | `data-collapsible` | offcanvas (default), icon or none. | | `data-state` | expanded (default) or collapsed: the desktop state. | | `data-breakpoint` | sm, md (default), lg or none: below it the sidebar is an off-canvas panel. | | `data-shortcut` | The Ctrl/⌘ shortcut's letter (b), or none. | | `data-cookie` | Cookie name to remember the state in (true/false). None by default. | | `data-open` | State, set by the behaviour: the mobile panel is open. | | `data-mobile` | State, set by the behaviour: the sidebar is in mobile mode. | | `data-sidebar-trigger` | Behaviour: toggles the sidebar in aria-controls (or its layout's); aria-expanded kept in sync. | | `data-sidebar-rail` | Behaviour: toggles the sidebar it's in. | | `data-sidebar-close` | Behaviour: closes the mobile panel, or collapses the sidebar. | | `sidebar:toggle` | Event on every change; detail { expanded, open, mobile }. | | `--sidebar-width` | Expanded width (16rem). | | `--sidebar-width-icon` | Icon rail width (3rem). | | `--sidebar-width-mobile` | Mobile panel width (18rem). | | `--sidebar-top` | Sticky offset and height reduction (0). | | `--skeleton-width` | Width of a .sidebar-menu-skeleton-text bar (70%). | | `--sidebar, --sidebar-*` | Colour tokens; see Theming. |