Componentnavigation

Sidebar

Stable

O painel lateral de uma aplicação: um provider que guarda o estado aberto, um painel que é coluna fixa em tela larga e Sheet abaixo de md, e as partes do menu que vão dentro dele. Recolhe para fora da borda ou para uma coluna de ícones, e o estado desktop fica lembrado em cookie para o servidor renderizar onde a pessoa deixou. Compõe Button, Input, Separator, Sheet, Skeleton e Tooltip do Up Web DS; o hook useIsMobile é um support module (shadcn/use-mobile) que viaja com o item em vez de virar item do catálogo.

Instalação

npx up-web-ds add sidebar

Gera sidebar para a biblioteca de ícones do projeto (components.json → iconLibrary).

Preview

Basic

Default

Collapsible Icon

Floating

Inset

Right

With Submenu

Loading

Usage

Imports de Sidebar

import {
  Sidebar,
  SidebarContent,
  SidebarGroup,
  SidebarGroupContent,
  SidebarGroupLabel,
  SidebarInset,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarTrigger,
} from '@/components/sidebar'
import { BoxIcon, ShapesIcon } from 'lucide-react'

Sidebar

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36<SidebarProvider>
  <Sidebar>
    <SidebarContent>
      <nav aria-label="Catálogo">
        <SidebarGroup>
          <SidebarGroupLabel>Catálogo</SidebarGroupLabel>
          <SidebarGroupContent>
            <SidebarMenu>
              <SidebarMenuItem>
                <SidebarMenuButton
                  isActive
                  render={<a href="#primitives" />}
                >
                  <ShapesIcon aria-hidden />
                  <span>Primitives</span>
                </SidebarMenuButton>
              </SidebarMenuItem>
              <SidebarMenuItem>
                <SidebarMenuButton render={<a href="#components" />}>
                  <BoxIcon aria-hidden />
                  <span>Components</span>
                </SidebarMenuButton>
              </SidebarMenuItem>
            </SidebarMenu>
          </SidebarGroupContent>
        </SidebarGroup>
      </nav>
    </SidebarContent>
  </Sidebar>
  <SidebarInset>
    <header className="flex h-16 shrink-0 items-center gap-2 border-b border-border px-4">
      <SidebarTrigger className="-ml-1" />
      <h1 className="type-small font-medium">Primitives</h1>
    </header>
  </SidebarInset>
</SidebarProvider>

Props

SidebarProvider

Props de SidebarProvider
Prop	Type	Default	Description
defaultOpen	`boolean`	`true`	Initial state when uncontrolled.
onOpenChange	`((open: boolean) => void)`	sem valor padrão
open	`boolean`	sem valor padrão	Controlled open state of the desktop panel.

Estende React.ComponentProps<'div'>. Aceita também os atributos padrão de um elemento React (280 não listados).

Sidebar

Props de Sidebar
Prop	Type	Default	Description
collapsible	`"none" \| "icon" \| "offcanvas"`	`'offcanvas'`	What collapsing does: slide away, shrink to icons, or nothing.
side	`"left" \| "right"`	`'left'`	Edge the panel is anchored to.
variant	`"inset" \| "sidebar" \| "floating"`	`'sidebar'`	Flush column, a floating card, or a column the page is inset from.

Estende React.ComponentProps<'div'>. Aceita também os atributos padrão de um elemento React (280 não listados).

SidebarTrigger

Props de SidebarTrigger
Prop	Type	Default	Description
size	`"default" \| "sm" \| "xs" \| "lg" \| "icon" \| "icon-xs" \| "icon-sm" \| "icon-lg" \| null`	sem valor padrão
variant	`"link" \| "destructive" \| "primary" \| "outline" \| "secondary" \| "ghost" \| null`	sem valor padrão
className	`string \| ((state: ButtonState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
focusableWhenDisabled	`boolean`	`false`	Whether the button should be focusable when disabled.
nativeButton	`boolean`	`true`	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ButtonState>`	sem valor padrão	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	`React.CSSProperties \| ((state: ButtonState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende ButtonProps. Aceita também os atributos padrão de um elemento React (285 não listados).

SidebarMenuButton

Props de SidebarMenuButton
Prop	Type	Default	Description
isActive	`boolean`	`false`	Marks the entry for the current page: `data-active`.
size	`"default" \| "sm" \| "lg" \| null`	`'default'`
tooltip	`string \| (TooltipPopupProps & Pick<TooltipPositionerProps, "side" \| "align" \| "sideOffset" \| "alignOffset"> & { showArrow?: boolean; })`	sem valor padrão	Shown beside the button only while the panel is collapsed to icons.
variant	`"default" \| "outline" \| null`	`'default'`
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, {}>`	sem valor padrão	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

Estende useRender.ComponentProps<'button'> & VariantProps<typeof sidebarMenuButtonVariants>. Aceita também os atributos padrão de um elemento React (290 não listados).

SidebarMenuAction

Props de SidebarMenuAction
Prop	Type	Default	Description
showOnHover	`boolean`	`false`	Reveal only while the entry is hovered or focused, on a wide screen.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, {}>`	sem valor padrão	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

Estende useRender.ComponentProps<'button'>. Aceita também os atributos padrão de um elemento React (290 não listados).

SidebarMenuSkeleton

Props de SidebarMenuSkeleton
Prop	Type	Default	Description
showIcon	`boolean`	`false`	Include the placeholder for the entry's icon.

Estende React.ComponentProps<'div'>. Aceita também os atributos padrão de um elemento React (280 não listados).

SidebarMenuSubButton

Props de SidebarMenuSubButton
Prop	Type	Default	Description
isActive	`boolean`	`false`	Marks the entry for the current page: `data-active`.
size	`"sm" \| "md"`	`'md'`
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, {}>`	sem valor padrão	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

Estende useRender.ComponentProps<'a'>. Aceita também os atributos padrão de um elemento React (288 não listados).

Composition

O provider envolve a página inteira: o painel e o SidebarInset são irmãos, e o gatilho pode estar em qualquer lugar dentro do provider.

Composição de SidebarProvider

SidebarProvider

SidebarProvider
- Sidebar
  - SidebarHeader
  - SidebarContent
    - SidebarGroup
      - SidebarGroupLabel
      - SidebarGroupAction
      - SidebarGroupContent
        SidebarMenu
        SidebarMenuItem
        SidebarMenuButton
        SidebarMenuAction
        SidebarMenuBadge
        SidebarMenuSub
        SidebarMenuSubItem
        SidebarMenuSubButton
  - SidebarFooter
  - SidebarRail
- SidebarInset
  - SidebarTrigger

Metadata

Notas de acessibilidade

Teclado verificado por teste e em navegador: o SidebarTrigger entra na sequência de tabulação, alterna com Enter e Espaço e mostra anel de foco, as entradas do menu são links ou botões reais com foco visível, e Ctrl ou Cmd + B alterna o painel sem roubar a letra B sozinha. O SidebarRail fica fora da sequência de tabulação de propósito: é uma área de clique na borda para ponteiro, e o caminho de teclado é o gatilho. Leitor de tela verificado por teste: gatilho e rail são nomeados por texto (Alternar barra lateral) e não pelo glifo, a entrada da página atual carrega data-active, SidebarInset é um landmark main por padrão, e abaixo de md o painel é um Sheet modal nomeado Barra lateral, que prende o foco, fecha com Escape e devolve o foco ao gatilho. Recolhido em ícones, cada entrada mantém o nome e reexibe o rótulo como tooltip. Touch verificado em navegador com emulação de toque em viewport de 375px: o gatilho abre o Sheet de 18rem deixando uma faixa da página visível, e todos os alvos medem acima do mínimo de 24x24. Reduced motion verificado em navegador com prefers-reduced-motion: reduce — recolher muda a largura e a posição do painel, e esse destino é o estado, então ele nunca é condicionado: sai só o tween (motion-reduce:transition-none no gap, no container, no rail, no rótulo do grupo e nos botões do menu), e o painel chega recolhido no primeiro frame. Nada ali espera transitionend; o Sheet usado no mobile mantém a política dele. Varredura axe WCAG 2.2 AA limpa em light e dark, desktop e mobile.

Classificação

Layer: Component
Domínio: Application
Categoria: navigation
Status: Stable

Origem e distribuição

Fonte: shadcn registry / sidebar
Licença: MIT
URL: https://ui.shadcn.com/r/styles/base-vega/sidebar.json
Distribuição: Interna

Acessibilidade

Teclado: revisado
Leitor de tela: revisado
Touch: revisado
Reduced motion: revisado

Dependências

Pacotes: @base-ui/react, class-variance-authority
Ícones: sidebar
Construído sobre: Button Input Separator Sheet Skeleton Tooltip
Usado por: Nenhum ainda