Navigation
Sidebar
An app shell with a collapsible sidebar that shrinks to icons on a wide screen and opens as a drawer on a phone.
Preview
Section titled “Preview”Installation
Section titled “Installation”Install the package for a versioned dependency:
npm install @nana-tec/ui-componentsOr copy the source in and own it:
npx @nana-tec/ui add sidebar-layout --framework web-componentsnpx @nana-tec/ui add sidebar --framework svelteLands in src/lib/components/ui/sidebar/, styled with Tailwind classes that resolve to the
design tokens. Requires Tailwind v4.
Import
Section titled “Import”
Import the autoloader once, in your app's entry point. Every <nana-*> tag then works anywhere, and
each component downloads only the first time a page uses it:
import "@nana-tec/ui-components/autoloader";import "@nana-tec/ui-components/theme";The second line gives every component the Nana look and the design tokens behind it. Leave it out to style the components entirely yourself.
Import a component directly when it must be ready at once: on screen at first paint, or when you call its methods straight away. The two mix freely:
import "@nana-tec/ui-components/sidebar-layout";
Copied in with npx @nana-tec/ui add sidebar-layout? Import your project's own
@/lib/nana-ui/autoloader.js once instead; the CLI keeps it up to date.
<script lang="ts"> import { homeIcon } from '@nana-tec/ui-core/heroicons'; import { NanaSidebarLayout, NanaSidebar, NanaSidebarContent, NanaSidebarGroup, NanaSidebarItem, NanaSidebarInset, NanaSidebarTrigger, } from '$lib/components/ui/sidebar';</script>
<NanaSidebarLayout label="Main"> <NanaSidebar> <NanaSidebarContent> <NanaSidebarGroup label="Workspace"> <NanaSidebarItem label="Dashboard" icon={homeIcon} href="/" active /> </NanaSidebarGroup> </NanaSidebarContent> </NanaSidebar> <NanaSidebarInset> <NanaSidebarTrigger /> <!-- the page --> </NanaSidebarInset></NanaSidebarLayout>Anatomy
Section titled “Anatomy”NanaSidebarLayout holds the state and wraps the whole page. Inside it, NanaSidebar is the
navigation, with an optional NanaSidebarHeader and NanaSidebarFooter pinned around a
scrolling NanaSidebarContent. NanaSidebarGroup gives a labelled list of NanaSidebarItems.
NanaSidebarInset is the page’s <main>, and NanaSidebarTrigger can sit anywhere in the
layout. Read the state from your own components with useSidebar().
nana-sidebar-layout wraps the whole page. Put nana-sidebar-group elements in its sidebar
slot, and anything pinned above or below them in sidebar-header and sidebar-footer. Every
other child is the page, rendered in a <main>. nana-sidebar-trigger can sit anywhere in the
layout; the layout keeps it, and every item, in step with the sidebar.
Variants
Section titled “Variants”variant changes how the sidebar sits beside the page. The parts, the collapsing and the
phone drawer stay the same.
| Variant | Look |
|---|---|
sidebar | The default. Flush to the edge of the screen, with a line between it and the page. |
floating | A rounded card in a small gutter, lifted with a light shadow. |
inset | The sidebar blends into the background, and the page sits in a raised, rounded panel beside it. |
<NanaSidebarLayout variant="inset"><nana-sidebar-layout variant="inset" label="Main">…</nana-sidebar-layout>Collapsed to icons, floating and inset keep their gutter, so the strip is 1rem wider than
--nana-sidebar-width-icon. On a phone every variant opens in the same drawer.
Collapsing
Section titled “Collapsing”collapsible="icon", the default, shrinks the sidebar to a strip of icons. Labels, badges and
group headings hide, and each item’s label moves into a tooltip. Clicking an item with a
sub-menu while collapsed expands the sidebar and opens it.
collapsible="offcanvas" slides the sidebar away completely, and makes it inert while it is
hidden so Tab skips it. collapsible="none" keeps it expanded.
Set side="right" to put the sidebar on the other side of the page.
Bind open to control it, or listen with onOpenChange.
<NanaSidebarLayout bind:open collapsible="offcanvas" onOpenChange={(next) => save(next)}>Set open to control it, call toggle(), or listen for nana-toggle.
layout.addEventListener('nana-toggle', (event) => save(event.detail.open));Remembering the choice
Section titled “Remembering the choice”Pass a storage key and the sidebar stores whether it is expanded in localStorage, then
restores it on the next visit.
<NanaSidebarLayout storageKey="app-sidebar"><nana-sidebar-layout storage-key="app-sidebar"></nana-sidebar-layout>Keyboard shortcut
Section titled “Keyboard shortcut”Ctrl+B, or ⌘B on Apple devices, toggles the sidebar from anywhere on the page. It does nothing
while focus is in a text field or editor, and nothing when another handler has already used
the key, so Bold keeps working in the editor. Change it with shortcut, such as mod+shift+s,
or turn it off with shortcut={false} in Svelte and shortcut="" on the web component.
Phones
Section titled “Phones”Below 768px the sidebar leaves the page and opens as a drawer from its side, at full height. The trigger opens and closes it, and following a link inside it closes it. Escape and the backdrop close it too, as with any Drawer.
Accessibility
Section titled “Accessibility”The sidebar is a <nav> named by label, and each group is a group named by its heading.
The trigger has aria-controls pointing at the sidebar and aria-expanded showing whether it
is open, or whether the drawer is open on a phone. The current page’s item carries
aria-current="page". An item with a sub-menu is a button with aria-expanded and
aria-controls. Collapsed to icons, every item keeps its label for screen readers.
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
collapsible | collapsible | SidebarCollapsible | 'icon' | icon collapses to a strip of icons, offcanvas slides the sidebar away, none keeps it expanded. |
label | label | string | 'Sidebar' | Accessible name of the navigation, also used for the drawer on a phone. |
open | open | boolean | true | Whether the sidebar is expanded on a wide screen. Set it to expand or collapse it yourself. |
shortcut | shortcut | — | SIDEBAR_SHORTCUT | Keyboard shortcut that toggles the sidebar. mod is ⌘ on Apple devices and Ctrl elsewhere. |
side | side | SidebarSide | 'left' | Puts the sidebar on the left or right of the page. |
storageKey | storage-key | string | '' | Remembers the expanded or collapsed state in localStorage under this key. |
variant | variant | SidebarVariant | 'sidebar' | sidebar sits flush to the edge, floating floats as a card in a gutter, inset raises the page into a panel beside it. |
Methods
| Method | Description |
|---|---|
toggle(): void | Expand or collapse the sidebar, or open and close its drawer on a phone |
Events
| Event | Description |
|---|---|
nana-toggle | Fired when the sidebar expands or collapses on a wide screen (detail.open) |
Slots
| Slot | Description |
|---|---|
(default) | The page beside the sidebar |
sidebar | The sidebar's scrolling content, usually nana-sidebar-group elements |
sidebar-header | Pinned to the top of the sidebar, such as a logo or a workspace switcher |
sidebar-footer | Pinned to the bottom of the sidebar, such as the signed-in user |
CSS parts
| Part | Description |
|---|---|
::part(panel) | The sidebar |
::part(header) | The sidebar's top area |
::part(content) | The sidebar's scrolling area |
::part(footer) | The sidebar's bottom area |
::part(drawer) | The drawer the sidebar opens in on a phone |
::part(inset) | The page beside the sidebar |
CSS custom properties
| Property | Description |
|---|---|
--nana-sidebar-width | Width of the expanded sidebar |
--nana-sidebar-width-icon | Width of the sidebar collapsed to icons |
--nana-sidebar-bg | Sidebar background |
--nana-sidebar-border | Line between the sidebar and the page, and beside a sub-menu |
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
collapsed | collapsed | boolean | false | Set by the layout while the sidebar shows icons only. |
label | label | string | '' | Heading of the group, hidden while the sidebar shows icons only. |
side | side | SidebarSide | 'left' | Set by the layout. |
Slots
| Slot | Description |
|---|---|
(default) | The nana-sidebar-item elements |
CSS parts
| Part | Description |
|---|---|
::part(group) | The group |
::part(label) | The group's label, hidden while the sidebar shows icons only |
::part(menu) | The list of items |
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
active | active | boolean | false | Marks the item as the current page. |
badge | badge | string | '' | Short text after the label, such as a count. |
collapsed | collapsed | boolean | false | Set by the layout while the sidebar shows icons only. |
disabled | disabled | boolean | false | Blocks interaction. |
href | href | string | '' | Makes the item a link to this address. |
icon | icon | string | '' | Name of a registered icon shown before the label. |
label | label | string | '' | The item's text, and its tooltip while the sidebar shows icons only. |
open | open | boolean | false | Whether the sub-menu is open, when the item has nested items. |
side | side | SidebarSide | 'left' | Set by the layout, to place the tooltip away from the edge. |
Slots
| Slot | Description |
|---|---|
items | Nested nana-sidebar-item elements, shown as a sub-menu |
CSS parts
| Part | Description |
|---|---|
::part(button) | The link or button, with active on the current page |
::part(icon) | The icon |
::part(label) | The label, hidden while the sidebar shows icons only |
::part(badge) | The badge |
::part(chevron) | The sub-menu's arrow, with open while the sub-menu is open |
::part(sub) | The sub-menu |
CSS custom properties
| Property | Description |
|---|---|
--nana-sidebar-accent | Background of a hovered or active item |
--nana-sidebar-border | Line beside a sub-menu |
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
expanded | expanded | boolean | true | Set by the layout to match the sidebar. |
label | label | string | 'Toggle sidebar' | Accessible name of the button. |
Slots
| Slot | Description |
|---|---|
(default) | Replaces the icon |
CSS parts
| Part | Description |
|---|---|
::part(trigger) | The button |
NanaSidebarGroup
| Prop | Type |
|---|---|
label | string |
children | Snippet |
Also accepts Omit<
HTMLAttributes<HTMLDivElement>,
'class'
>.
NanaSidebarItem
| Prop | Type | Default |
|---|---|---|
labelrequired | string | |
href | string | |
icon | IconDefinition | |
active | boolean | false |
badge | string | number | |
openbind: | boolean | false |
disabled | boolean | false |
onclick | (event: MouseEvent) => void | |
items | Snippet |
NanaSidebarLayout
| Prop | Type | Default |
|---|---|---|
openbind: | boolean | true |
onOpenChange | (open: boolean) => void | |
collapsible | SidebarCollapsible | 'icon' |
side | SidebarSide | 'left' |
variant | SidebarVariant | 'sidebar' |
label | string | 'Sidebar' |
storageKey | string | |
shortcut | string | false | SIDEBAR_SHORTCUT |
children | Snippet |
Also accepts Omit<HTMLAttributes<HTMLDivElement>, 'class'>.
NanaSidebarTrigger
| Prop | Type | Default |
|---|---|---|
label | string | 'Toggle sidebar' |
onclick | (event: MouseEvent) => void | |
children | Snippet |
Also accepts Omit<ComponentProps<typeof NanaButton>, 'class' | 'onclick' | 'children'>.