Componentes

Sidebar

beta

A navegação lateral inteira: provider, grupos, menu, estado recolhido e comportamento em celular. Nas telas do produto ela entra pelo slot nav da casca, não montada à mão.

Ainda não é estável porque Rota não varrida pelo sensor. Ausência de medição não é aprovação. O contrato de maturidade explica o que cada requisito exige.

@voxmente/ui/components/ui/sidebar

Orientação

A navegação lateral inteira: provider, grupos, menu, estado recolhido e comportamento em celular. Nas telas do produto ela entra pelo slot nav da casca, nunca montada à mão.

Quando usar

A tela é autenticada e precisa da navegação persistente entre as frentes do produto.
A navegação tem grupos com rótulo, e o usuário precisa reconhecer onde está.
É preciso recolher a barra para dar espaço ao conteúdo sem perder o acesso aos destinos.

Quando não usar

Para ações. Barra lateral navega; ação é botão, e ação contextual é Dropdown Menu.
Em página institucional pública, onde a navegação é de topo — ali o componente é o Navigation Menu.
Montada solta numa tela: em produto, quem posiciona a barra é a Casca de tela.

Playground

Variantevariant

Tamanhosize

Rótulochildren

AtivoisActive

<SidebarMenuButton>
  <ChalkboardTeacher />
  <span>Turmas</span>
</SidebarMenuButton>

Anatomia

As partes deste componente e como se aninham. A árvore vem das demonstrações desta página, então descreve um exemplo que renderiza.

SidebarProvider
  └─ Sidebar
    └─ SidebarContent
      └─ SidebarGroup
        └─ SidebarGroupLabel
        └─ SidebarGroupAction
        └─ SidebarGroupContent
          └─ SidebarMenu
            └─ SidebarMenuItem
              └─ SidebarMenuButton
              └─ SidebarMenuBadge
            └─ SidebarMenuItem
              └─ SidebarMenuButton
              └─ SidebarMenuAction

Exportadas, mas sem demonstração nesta página: SidebarInput, SidebarInset, SidebarMenuSkeleton, SidebarSeparator.

Composição

São 23 partes. A árvore abaixo é o mapa: quase todo problema com esta barra é peça no lugar errado, não prop faltando.

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

Guarda o estado de recolhimento e o distribui por contexto. Tudo dentro da barra depende dele: usar qualquer peça fora do provider lança em execução, não em tipo. Ele também registra o atalho ⌘B (Ctrl+B no Windows) e escreve o estado num cookie, para a escolha sobreviver ao recarregamento.

Largura por variável: --sidebar-width e --sidebar-width-icon, definidas pelo provider e sobrescritíveis por style.

Modos de recolhimento

`collapsible` decide o que acontece quando a barra fecha: `icon` mantém os ícones visíveis, `offcanvas` tira a barra de cena, `none` remove o recolhimento — e, nesse caso, `variant` e `side` deixam de ter efeito, porque o componente cai num caminho mais curto.

Abrir em nova aba

Variantes e lado

`variant` muda como a barra se apoia na página: `sidebar` encosta na borda, `floating` ganha cantos e sombra, `inset` recua o conteúdo. Com `inset`, o miolo precisa estar dentro de `SidebarInset` — sem isso o recuo não acontece. `side` aceita `left` e `right`.

Abrir em nova aba

Gatilho e trilho

`SidebarTrigger` é o botão que abre e fecha. `SidebarRail` é a faixa fina na borda da barra que faz a mesma coisa — existe para quem já sabe onde clicar. Os dois só funcionam dentro do provider.

Abrir em nova aba

useSidebar

Para controlar a barra de fora dos componentes dela. Lança se chamado fora do provider — é a restrição que mais derruba tela nova.

Campo	O que é
state	"expanded" ou "collapsed"
open / setOpen	estado no desktop
openMobile / setOpenMobile	estado no celular, onde a barra vira gaveta
isMobile	abaixo de 768px
toggleSidebar	alterna o que for pertinente ao viewport atual

Uso

Navegação fixa de uma tela autenticada. Tudo aqui — inclusive o próprio Sidebar — só existe dentro de um SidebarProvider: sem ele, useSidebar() lança e a página quebra.

Variantes do item

`SidebarMenuButton` tem duas variantes: `default` se funde ao fundo da barra, `outline` recorta o item — use quando o item precisa competir com um conteúdo mais carregado ao lado.

Tamanhos do item

`sm`, `default` e `lg` mudam a altura do item de menu. Use `lg` quando o item carrega uma segunda linha de informação, não por decoração.

Contador e ação

`SidebarMenuBadge` marca uma contagem — pendências, não lidos. `SidebarMenuAction` é um botão extra sobre o item, e `SidebarGroupAction` faz o mesmo no nível do grupo. Nenhum dos dois substitui o clique principal do item.

Submenu

`SidebarMenuSub` aninha `SidebarMenuSubItem` e `SidebarMenuSubButton` sob um `SidebarMenuItem`. É uma lista à parte — não é um `SidebarMenu` dentro de outro. Some sozinho quando a barra colapsa para ícone.

Na tela

Nas telas autenticadas do VoxMente a barra lateral não é montada à mão: ela entra pelo slot `nav` do ScreenSkeleton, que já embrulha tudo em SidebarProvider e usa collapsible="icon". Abaixo de 768px a barra vira gaveta, e a casca monta sozinha uma faixa com `SidebarTrigger` — nenhuma tela precisa lembrar disso, e no desktop essa faixa não existe. Recolhida, a barra mostra só ícones: todo `SidebarMenuButton` de navegação precisa de `tooltip`, que é o único rótulo que sobra.

Acessibilidade

O que o componente já garante, e o que continua sendo responsabilidade da tela.

Em telas estreitas a barra vira camada; o gatilho precisa continuar alcançável e anunciar que abre a navegação.
O item atual precisa ser marcado como atual, não apenas pintado diferente.
A ordem de foco tem que sair da barra para o conteúdo sem armadilha — verifique com Tab antes de considerar a tela pronta.

Em contexto de produto

Onde isto aparece numa tela real da Vox Mente, e não numa vitrine.

No painel do professor a barra entra pela casca, com os grupos da operação e o rodapé de identidade da pessoa logada.

Ver o painel do professor

Componentes relacionados

Vizinhos que resolvem o problema parecido. Os links são resolvidos contra o registro.

Referência da API

Extraída do TypeScript de @voxmente/ui a cada build. Se divergir do código, o código mudou.

Sidebar

Prop	Tipo	Padrão
collapsible	"none" \| "icon" \| "offcanvas"	"offcanvas"
side	"left" \| "right"	"left"
variant	"sidebar" \| "floating" \| "inset"	"sidebar"

Também aceita as props de React, incluindo className e os atributos de DOM.

SidebarMenuAction

Prop	Tipo	Padrão
showOnHover	boolean	false

Também aceita as props de Base UI e React, incluindo className e os atributos de DOM.

SidebarMenuButton

Prop	Tipo	Padrão
isActive	boolean	false
size	"md" \| "sm" \| "lg" \| null	"md"
tooltip	string \| (TooltipPopupProps & Pick<TooltipPositionerProps, "align" \| "side" \| "sideOffset" \| "alignOffset">)	—
variant	"default" \| "outline" \| null	"default"

Também aceita as props de Base UI e React, incluindo className e os atributos de DOM.

SidebarMenuSkeleton

Prop	Tipo	Padrão
showIcon	boolean	false

Também aceita as props de React, incluindo className e os atributos de DOM.

SidebarMenuSubButton

Prop	Tipo	Padrão
isActive	boolean	false
size	"md" \| "sm"	"md"

Também aceita as props de Base UI e React, incluindo className e os atributos de DOM.

SidebarProvider

Prop	Tipo	Padrão
defaultOpen	boolean	true
onOpenChange	((open: boolean) => void)	—
open	boolean	—

Também aceita as props de React, incluindo className e os atributos de DOM.

SidebarTrigger

Prop	Tipo	Padrão
size	"md" \| "xs" \| "sm" \| "lg" \| "icon-md" \| "icon-xs" \| "icon-sm" \| "icon-lg" \| null	—
variant	"link" \| "default" \| "outline" \| "secondary" \| "ghost" \| "destructive" \| null	—

Também aceita as props de Base UI e React, incluindo className e os atributos de DOM.

SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupAction, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInput, SidebarInset, SidebarMenu, SidebarMenuBadge, SidebarMenuItem, SidebarMenuSub, SidebarMenuSubItem, SidebarRail, SidebarSeparator não têm props próprias — aceitam apenas as props herdadas, incluindo className e os atributos de DOM.

Origem do dado

Orientação, acessibilidade e relacionados: documentação
Anatomia: exemplo desta página
Demonstrações e playground: componente real de @voxmente/ui
Referência da API: TypeScript do pacote
Cor, espaçamento e raio das demonstrações: tokens de theme.css