Sidebar

Overview

Sidebar é o componente mais composto do KDS — 20+ subcomponentes que combinam para formar uma navegação lateral de aplicação tipo SaaS / dashboard. Header (logo / team switcher), Content (groups de menu items), Footer (suporte / settings / user) — toda a anatomia esperada de produtos como Linear, Vercel, Notion.

Aviso sobre estes previews. Os exemplos abaixo são escopados dentro de cards com seu próprio SidebarProvider. Não monte um <SidebarProvider> global em apps/docs/app/layout.tsx — o Fumadocs já tem sua própria sidebar, e dois providers concorrendo quebram focus management e medições. Cada Card aqui é um shell isolado.

Anatomy

<SidebarProvider>
  <Sidebar>
    <SidebarHeader>
      {/* logo, team switcher, search */}
    </SidebarHeader>
    <SidebarContent>
      <SidebarGroup>
        <SidebarGroupLabel>Workspace</SidebarGroupLabel>
        <SidebarGroupContent>
          <SidebarMenu>
            <SidebarMenuItem>
              <SidebarMenuButton isActive>
                <Icon /> Label
                <SidebarMenuBadge>4</SidebarMenuBadge>
              </SidebarMenuButton>
            </SidebarMenuItem>
          </SidebarMenu>
        </SidebarGroupContent>
      </SidebarGroup>
    </SidebarContent>
    <SidebarFooter>
      {/* user menu, support */}
    </SidebarFooter>
  </Sidebar>
  <SidebarInset>
    {/* main app content */}
  </SidebarInset>
</SidebarProvider>

SidebarProvider é obrigatório como ancestor de qualquer Sidebar ou useSidebar(). Ele guarda o estado expanded/collapsed, detecta mobile, e instala o atalho ⌘B para toggle.

Subcomponents

Usage

import {
  Sidebar,
  SidebarContent,
  SidebarHeader,
  SidebarInset,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarTrigger
} from "@kalvner/kds/navigation/sidebar";

export default function AppLayout({ children }) {
  return (
    <SidebarProvider>
      <Sidebar>
        <SidebarHeader>…</SidebarHeader>
        <SidebarContent>
          <SidebarMenu>
            <SidebarMenuItem>
              <SidebarMenuButton isActive>Início</SidebarMenuButton>
            </SidebarMenuItem>
          </SidebarMenu>
        </SidebarContent>
      </Sidebar>
      <SidebarInset>
        <header>
          <SidebarTrigger />
        </header>
        <main>{children}</main>
      </SidebarInset>
    </SidebarProvider>
  );
}

Composition

Variants

When to use

• SaaS / dashboards / internal tools com nav lateral persistente.
• Apps com ≥6 destinos top-level que precisam de agrupamento.
• Quando hierarquia de seções é a primeira affordance da app (Linear, Notion, Vercel).

When not to use

• Sites de marketing — use NavigationMenu.
• Apps com ≤4 destinos — overhead. Use Tabs ou navbar simples.
• Conteúdo focado (artigo, formulário longo) — sidebar concorre com a leitura.
• Em telas pequenas como nav primária — em mobile, vira Sheet (já acontece automaticamente quando useIsMobile() detecta).

Best practices

• Agrupe por propósito, não por tipo. "Workspace > Ferramentas

  Admin" beats "Pages > Components > Settings".

• Active state vem do router. Sidebar não detecta rota — o consumidor passa isActive no item correspondente.
• Badges para counts, não para status. Inbox (4) é OK; "Novo" como badge não é. Use ícone de status.
• Footer enxuto. User menu, settings, suporte. Não é lugar para CTAs.
• Persista o estado. O SidebarProvider já grava em cookie por default; honre o estado restaurado do cookie em SSR para evitar layout shift.
• Keyboard shortcut respeite ⌘B. É o padrão da indústria (VS Code, Linear, Notion). Não troque.

Accessibility

Related

• Tabs — alternar dentro de uma view.
• NavigationMenu — header de marketing.
• Sheet — usado por baixo dos panos em mobile.