Side Nav

A grouped list of links that turns into a scrolling row on small screens.

import {
  BellIcon,
  BlocksIcon,
  CreditCardIcon,
  SettingsIcon,
  ShieldIcon,
  UserIcon,
  UserPlusIcon,
  UsersIcon,
} from "lucide-react";
import * as React from "react";

import { Button } from "@/components/ui/button";
import {
  PageHeader,
  PageHeaderActions,
  PageHeaderContent,
  PageHeaderDescription,
  PageHeaderTitle,
} from "@/components/ui/page-header";
import { SideNav, SideNavGroup, SideNavItem } from "@/components/ui/side-nav";

const groups = [
  {
    label: "Account",
    items: [
      { id: "profile", label: "Profile", icon: UserIcon },
      { id: "security", label: "Security", icon: ShieldIcon },
      { id: "notifications", label: "Notifications", icon: BellIcon },
    ],
  },
  {
    label: "Organization",
    items: [
      { id: "general", label: "General", icon: SettingsIcon },
      { id: "members", label: "Members", icon: UsersIcon },
      { id: "billing", label: "Billing", icon: CreditCardIcon },
      { id: "integrations", label: "Integrations", icon: BlocksIcon },
    ],
  },
];

const pages: Record<string, { description: string; action?: React.ReactNode }> = {
  profile: { description: "How you appear to your teammates.", action: "Save" },
  security: { description: "Keep your account safe." },
  notifications: { description: "Choose what we email you about.", action: "Save" },
  general: { description: "Your workspace's name, address and language.", action: "Save" },
  members: {
    description: "6 people have access to Acme.",
    action: (
      <>
        <UserPlusIcon />
        Invite
      </>
    ),
  },
  billing: { description: "You're on the Team plan, billed monthly." },
  integrations: { description: "Connect Acme to the tools your team uses." },
};

export default function SideNavSettingsPage() {
  const [active, setActive] = React.useState("general");
  const title = groups.flatMap((group) => group.items).find((item) => item.id === active)?.label;
  const { description, action } = pages[active];

  return (
    <div className="grid w-full grid-cols-1 gap-6 lg:grid-cols-[11rem_minmax(0,1fr)]">
      <SideNav aria-label="Settings">
        {groups.map((group) => (
          <SideNavGroup key={group.label} label={group.label}>
            {group.items.map(({ id, label, icon: Icon }) => (
              <SideNavItem
                key={id}
                href="#"
                active={active === id}
                icon={<Icon />}
                onClick={(event) => {
                  event.preventDefault();
                  setActive(id);
                }}
              >
                {label}
              </SideNavItem>
            ))}
          </SideNavGroup>
        ))}
      </SideNav>
      <PageHeader size="sm" className="self-start">
        <PageHeaderContent>
          <PageHeaderTitle render={<h3 />}>{title}</PageHeaderTitle>
          <PageHeaderDescription>{description}</PageHeaderDescription>
        </PageHeaderContent>
        {action != null && (
          <PageHeaderActions>
            <Button variant="secondary" size="sm">
              {action}
            </Button>
          </PageHeaderActions>
        )}
      </PageHeader>
    </div>
  );
}

Installation

Add the registryOnce per project
pnpm dlx shadcn@latest registry add @jarvis=https://ui.jarv.is/r/{name}.json
Add side-nav
pnpm dlx shadcn@latest add @jarvis/side-nav

Usage

import { SideNav, SideNavGroup, SideNavItem } from "@/components/ui/side-nav";

export function SettingsNav() {
  return (
    <SideNav aria-label="Settings">
      <SideNavGroup label="Account">
        <SideNavItem href="/settings/profile" active>
          Profile
        </SideNavItem>
        <SideNavItem href="/settings/security">Security</SideNavItem>
      </SideNavGroup>
      <SideNavGroup label="Organization">
        <SideNavItem href="/settings/members">Members</SideNavItem>
        <SideNavItem href="/settings/billing">Billing</SideNavItem>
      </SideNavGroup>
    </SideNav>
  );
}

Give SideNav an aria-label and set active on the current page's item. Below the lg breakpoint the list becomes a scrolling row, so place it above the content on small screens. The active item scrolls into view, and the edges fade wherever there's more to scroll. To keep one layout at every width, set orientation.

The active item announces itself as the current page. For links to sections of one page, pass aria-current="location" along with active.

To use your router's link, pass it to render on SideNavItem, as in render={<Link to="/settings/profile" />}.

Composition

SideNav
- SideNavGroup
  - SideNavItem

Examples

Without groups

Put SideNavItems directly in SideNav for a short list.

import * as React from "react";

import { SideNav, SideNavItem } from "@/components/ui/side-nav";

const pages = ["Overview", "Activity", "Deployments", "Analytics", "Logs", "Settings"];

export default function SideNavWithoutGroups() {
  const [active, setActive] = React.useState("Overview");

  return (
    <SideNav aria-label="Project" className="w-full lg:w-44">
      {pages.map((page) => (
        <SideNavItem
          key={page}
          href="#"
          active={active === page}
          onClick={(event) => {
            event.preventDefault();
            setActive(page);
          }}
        >
          {page}
        </SideNavItem>
      ))}
    </SideNav>
  );
}

Orientation

orientation is responsive by default, a row below lg and a column from it. Set it to horizontal to keep the scrolling row at every width, as in a bar of a page's sections, or to vertical to keep the column, as in a menu drawer on a phone.

import * as React from "react";

import { SideNav, SideNavItem } from "@/components/ui/side-nav";
import { preventNavigation } from "@/examples/data";

const pages = ["Overview", "Activity", "Deployments", "Analytics", "Logs", "Settings"];

export default function SideNavOrientation() {
  const [active, setActive] = React.useState("Overview");

  const items = pages.map((page) => (
    <SideNavItem
      key={page}
      href="#"
      active={active === page}
      onClick={(event) => {
        preventNavigation(event);
        setActive(page);
      }}
    >
      {page}
    </SideNavItem>
  ));

  return (
    <div className="flex w-full max-w-md flex-col gap-6">
      <SideNav aria-label="Project, as a row" orientation="horizontal">
        {items}
      </SideNav>
      <SideNav aria-label="Project, as a column" orientation="vertical" className="w-44">
        {items}
      </SideNav>
    </div>
  );
}

Scrolling

Give SideNav a height to scroll a long list in the sidebar. It's a Scroll Area, so it fades at the edges and shows a scrollbar on hover.

import * as React from "react";

import { SideNav, SideNavGroup, SideNavItem } from "@/components/ui/side-nav";

const groups = [
  { label: "Account", pages: ["Profile", "Security", "Notifications", "Connected apps"] },
  { label: "Organization", pages: ["General", "Members", "Teams", "Roles", "Billing"] },
  { label: "Developers", pages: ["API keys", "Webhooks", "Audit log"] },
];

export default function SideNavScrolling() {
  const [active, setActive] = React.useState("Webhooks");

  return (
    <SideNav aria-label="Settings" className="w-full lg:h-64 lg:w-44">
      {groups.map((group) => (
        <SideNavGroup key={group.label} label={group.label}>
          {group.pages.map((page) => (
            <SideNavItem
              key={page}
              href="#"
              active={active === page}
              onClick={(event) => {
                event.preventDefault();
                setActive(page);
              }}
            >
              {page}
            </SideNavItem>
          ))}
        </SideNavGroup>
      ))}
    </SideNav>
  );
}

Props

Part	Extends
SideNav	ScrollArea
SideNavGroup	<div>
SideNavItem	<a>

The tables leave out className, style and render. Parts built on Base UI take them as its styling and composition guides describe.

SideNav

Prop	Type	Default
`overflowEdgeThreshold` The threshold in pixels that must be passed before the overflow edge attributes are applied. Accepts a single number for all edges or an object to configure them individually.	`number \| Partial<{ xStart: number; xEnd: number; yStart: number; yEnd: number; }>`	`0`
`scrollFade` Fades the content out at any edge it can scroll past, and keeps focused content clear of the fade. Set `--scroll-fade-size` on the root to change the fade (1.5rem by default), or pass `false` to turn it off.	`boolean`	`true`
`orientation` Lays the list out in a column, in a scrolling row, or in a row below the `lg` breakpoint and a column from it.	`"horizontal" \| "responsive" \| "vertical"`	`"responsive"`

SideNavGroup

Prop	Type	Default
`label`	`React.ReactNode`	—

SideNavItem

Prop	Type	Default
`active` Highlights the item, scrolls it into view and sets `aria-current="page"`. Pass `aria-current` to announce something else, such as `"location"` for a section of the page.	`boolean`	`false`
`icon`	`React.ReactNode`	—