Nav Sidebar

App navigation beside the page: docked, floating or inset. Collapses to a rail of icons or slides out, can peek open on hover, and becomes an overlay on narrow layouts.

Installation

pnpm dlx shadcn@latest add @jds/nav-sidebar

Usage

import {
  NavSidebar,
  NavSidebarContent,
  NavSidebarGroup,
  NavSidebarInset,
  NavSidebarItem,
  NavSidebarLayout,
  NavSidebarTrigger,
} from "@/components/navigation/nav-sidebar"

<NavSidebarLayout className="h-dvh">
  <NavSidebar collapse="icons">
    <NavSidebarContent>
      <NavSidebarGroup>
        <NavSidebarItem render={<Link href="/inbox" />} icon={<InboxIcon />} active badge={4}>
          Inbox
        </NavSidebarItem>
      </NavSidebarGroup>
    </NavSidebarContent>
  </NavSidebar>
  <NavSidebarInset>
    <header>
      <NavSidebarTrigger />
    </header>
    {children}
  </NavSidebarInset>
</NavSidebarLayout>

Examples

Floating, peeks open on hover

Inset, slides out

API Reference

NavSidebarLayout

Prop	Type	Default
`open` Controlled expanded state. Or defaultOpen with onOpenChange.	boolean	–
`defaultOpen` Starting state when uncontrolled.	boolean	true
`onOpenChange` Called when it expands or collapses.	(open: boolean) => void	–
`shortcut` Key that toggles it with ⌘ or Ctrl.	string \| false	"b"
`breakpoint` Layout width in px below which the sidebar becomes an overlay with a scrim.	number	768

NavSidebar

Prop	Type	Default
`side`	"left" \| "right"	"left"
`variant` Docked runs full height on the edge; floating is an inset card; inset puts the page in a card.	"docked" \| "floating" \| "inset"	"docked"
`collapse` Collapsed, it shrinks to a rail of icons, slides fully out, or never collapses.	"icons" \| "offcanvas" \| "none"	"icons"
`expandOnHover` With icons: hovering the rail opens it over the page until the pointer leaves.	boolean	false
`surface`	"sidebar" \| "background" \| "glass"	"sidebar"
`width` Expanded width in px.	number	256
`railWidth` Collapsed width in px, with icons.	number	56
`indicator` How the current page stands out. Fill and bar slide between items.	"fill" \| "bar" \| "text"	"fill"
`density`	"compact" \| "comfortable"	"comfortable"
`motion`	"spring" \| "tween"	"spring"

NavSidebarItem

Prop	Type	Default
`icon` Shown alone on the rail.	ReactNode	–
`active` The current page.	boolean	–
`badge` A count at the end. A dot on the rail.	ReactNode	–
`href` Renders a plain link. Without it, a button.	string	–
`render` Your router's link, e.g. <Link href=… />.	ReactElement	–

NavSidebarTrigger

Prop	Type	Default
`onlyWhenHidden` Render only while the sidebar is out of view. Use it in the page when your main trigger is in the sidebar.	boolean	false

Introduction