Skip to content
Nana UI

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.

View .md Download

Install the package for a versioned dependency:

npm install @nana-tec/ui-components

Or copy the source in and own it:

npx @nana-tec/ui add sidebar-layout --framework web-components
npx @nana-tec/ui add sidebar --framework svelte

Lands in src/lib/components/ui/sidebar/, styled with Tailwind classes that resolve to the design tokens. Requires Tailwind v4.

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>

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.

variant changes how the sidebar sits beside the page. The parts, the collapsing and the phone drawer stay the same.

VariantLook
sidebarThe default. Flush to the edge of the screen, with a line between it and the page.
floatingA rounded card in a small gutter, lifted with a light shadow.
insetThe 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.

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));

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>

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.

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.

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

PropertyAttributeTypeDefaultDescription
collapsiblecollapsibleSidebarCollapsible'icon'icon collapses to a strip of icons, offcanvas slides the sidebar away, none keeps it expanded.
labellabelstring'Sidebar'Accessible name of the navigation, also used for the drawer on a phone.
openopenbooleantrueWhether the sidebar is expanded on a wide screen. Set it to expand or collapse it yourself.
shortcutshortcut—SIDEBAR_SHORTCUTKeyboard shortcut that toggles the sidebar. mod is ⌘ on Apple devices and Ctrl elsewhere.
sidesideSidebarSide'left'Puts the sidebar on the left or right of the page.
storageKeystorage-keystring''Remembers the expanded or collapsed state in localStorage under this key.
variantvariantSidebarVariant'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

MethodDescription
toggle(): voidExpand or collapse the sidebar, or open and close its drawer on a phone

Events

EventDescription
nana-toggleFired when the sidebar expands or collapses on a wide screen (detail.open)

Slots

SlotDescription
(default)The page beside the sidebar
sidebarThe sidebar's scrolling content, usually nana-sidebar-group elements
sidebar-headerPinned to the top of the sidebar, such as a logo or a workspace switcher
sidebar-footerPinned to the bottom of the sidebar, such as the signed-in user

CSS parts

PartDescription
::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

PropertyDescription
--nana-sidebar-widthWidth of the expanded sidebar
--nana-sidebar-width-iconWidth of the sidebar collapsed to icons
--nana-sidebar-bgSidebar background
--nana-sidebar-borderLine between the sidebar and the page, and beside a sub-menu

Properties

PropertyAttributeTypeDefaultDescription
collapsedcollapsedbooleanfalseSet by the layout while the sidebar shows icons only.
labellabelstring''Heading of the group, hidden while the sidebar shows icons only.
sidesideSidebarSide'left'Set by the layout.

Slots

SlotDescription
(default)The nana-sidebar-item elements

CSS parts

PartDescription
::part(group)The group
::part(label)The group's label, hidden while the sidebar shows icons only
::part(menu)The list of items

Properties

PropertyAttributeTypeDefaultDescription
activeactivebooleanfalseMarks the item as the current page.
badgebadgestring''Short text after the label, such as a count.
collapsedcollapsedbooleanfalseSet by the layout while the sidebar shows icons only.
disableddisabledbooleanfalseBlocks interaction.
hrefhrefstring''Makes the item a link to this address.
iconiconstring''Name of a registered icon shown before the label.
labellabelstring''The item's text, and its tooltip while the sidebar shows icons only.
openopenbooleanfalseWhether the sub-menu is open, when the item has nested items.
sidesideSidebarSide'left'Set by the layout, to place the tooltip away from the edge.

Slots

SlotDescription
itemsNested nana-sidebar-item elements, shown as a sub-menu

CSS parts

PartDescription
::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

PropertyDescription
--nana-sidebar-accentBackground of a hovered or active item
--nana-sidebar-borderLine beside a sub-menu

Properties

PropertyAttributeTypeDefaultDescription
expandedexpandedbooleantrueSet by the layout to match the sidebar.
labellabelstring'Toggle sidebar'Accessible name of the button.

Slots

SlotDescription
(default)Replaces the icon

CSS parts

PartDescription
::part(trigger)The button

NanaSidebarGroup

PropType
labelstring
childrenSnippet

Also accepts Omit< HTMLAttributes<HTMLDivElement>, 'class' >.

NanaSidebarItem

PropTypeDefault
labelrequiredstring
hrefstring
iconIconDefinition
activebooleanfalse
badgestring | number
openbind:booleanfalse
disabledbooleanfalse
onclick(event: MouseEvent) => void
itemsSnippet

NanaSidebarLayout

PropTypeDefault
openbind:booleantrue
onOpenChange(open: boolean) => void
collapsibleSidebarCollapsible'icon'
sideSidebarSide'left'
variantSidebarVariant'sidebar'
labelstring'Sidebar'
storageKeystring
shortcutstring | falseSIDEBAR_SHORTCUT
childrenSnippet

Also accepts Omit<HTMLAttributes<HTMLDivElement>, 'class'>.

NanaSidebarTrigger

PropTypeDefault
labelstring'Toggle sidebar'
onclick(event: MouseEvent) => void
childrenSnippet

Also accepts Omit<ComponentProps<typeof NanaButton>, 'class' | 'onclick' | 'children'>.