Pular para o conteúdo
Navegação

Sidebar

/componentes/sidebar.mdmarkdown cru, para quem lê com agent em vez de olho

Tela de operação

Pedidos

Feche a barra pelo botão, ou por Ctrl+B, e ela encolhe até a coluna de ícones. O submenu vira menu ao lado, em vez de sumir.

Carregando a navegação

Com o link do router

O render troca a âncora pelo link do router e mantém o desenho da linha. Estes três levam à demonstração.
Importar
import { Sidebar } from '@rivocode/ui'

Quando usar

A barra lateral de uma tela de operação. Não é só um menu: é provedor de estado, barra, busca, grupos, itens, submenu, rodapé, gatilho e a área da página ao lado.

Fechada quer dizer coisas diferentes em cada largura. Na mesa, encolhida até a coluna de ícones, com o nome de cada item virando dica ao passar o mouse. No celular, fora da tela, e a barra vira a folha da lateral.

O atalho é Ctrl+B, ou Cmd+B no Mac, o mesmo do editor. Quem trabalha o dia inteiro numa tela de operação abre e fecha isso dezenas de vezes. Dentro de um campo de texto ou do RichTextEditor ele não dispara, porque ali o Ctrl+B é negrito; e shortcut ignora maiúscula, então "B" e "b" são o mesmo atalho.

Encolhida, nada some

É onde quase toda barra lateral falha. Encolher para 3,5rem costuma esconder a busca, cortar o título do grupo no meio da palavra e sumir com os submenus, deixando parte do sistema sem caminho enquanto a barra estiver fechada.

Aqui cada peça sabe o que fazer nessa largura:

  • SidebarInput vira o ícone da lupa, que abre a barra de volta. Um campo de texto de 3,5rem não aceita nem uma palavra.
  • SidebarMenuSub vira um menu que salta ao lado, com os mesmos filhos. Indentar não cabe; esconder seria pior.
  • SidebarGroup esconde o título. Sumir diz menos, mentir sobre o nome do grupo diz errado.
  • SidebarMenuItem mostra só o ícone, com o nome na dica. Sem a dica, a coluna de ícones vira adivinhação, e é por isso que tanta barra encolhida só serve para quem já decorou o sistema.

As peças

SidebarProvider guarda o estado e o atalho. Sidebar é a coluna, com side="left" ou "right". Dentro dela: SidebarHeader, SidebarInput, SidebarContent, SidebarGroup, SidebarMenu, SidebarMenuItem, SidebarMenuSub, SidebarSeparator, SidebarFooter.

SidebarMenuRow com SidebarMenuAction dentro dá a uma linha o botão secundário que aparece ao passar o mouse. SidebarMenuSkeleton ocupa o lugar enquanto a navegação vem do servidor. SidebarRail é a faixa fina na borda que abre e fecha ao ser clicada, e SidebarTrigger é o botão que faz o mesmo pelo teclado. O nome dele acompanha o que ele faz ali: na mesa, "Recolher barra lateral" e "Expandir barra lateral", porque a barra vira a coluna de ícones e não some; no celular, "Abrir menu" e "Fechar menu", porque ali ela é uma folha.

SidebarMenuItem é item de lista dentro de SidebarMenu, e link solto fora dele. No SidebarFooter, embrulhe os itens num SidebarMenu quando forem mais de um; um item só pode ficar solto, sem virar li fora de lista.

SidebarInset é a área da página, ao lado da barra.

O miolo rola sem a barra do sistema

Quando a busca, os grupos e o rodapé não cabem na altura, só o SidebarContent rola, e ele rola numa ScrollArea com fade: a barra de rolagem fica por cima dos itens, sem tomar largura, e só aparece ao passar o ponteiro ou enquanto rola. Com o macOS em "mostrar sempre" ou com mouse ligado, a barra do sistema ficaria pintada ao lado do menu o tempo todo, e na coluna de ícones comeria um quarto da largura.

A borda de cima e a de baixo esmaecem quando há item escondido daquele lado, que é o aviso de que a lista continua, já que a barra não fica à vista. O esmaecido é máscara, e não cor, então serve igual na barra e na folha do celular. Pelo teclado nada muda: o Tab rola até o item, que para longe da borda esmaecida, e a área ganha uma parada de Tab própria só quando rola, para quem lê com as setas.

O className continua vestindo a coluna dos grupos (o flex-col gap-4), e os outros atributos e o ref vão para ela também. A moldura que ocupa a sobra da barra e a caixa que rola ficam um e dois níveis acima, e se vestem por classNames:

<SidebarContent className="gap-2" classNames={{ root: "-mx-1", viewport: "px-1" }}>
  …
</SidebarContent>

SidebarBrand é a marca no topo, e encolhe junto com a barra: aberta mostra o nome ao lado do símbolo, na coluna de ícones mostra só o símbolo.

description põe uma linha menor embaixo do nome: a empresa da conta, quando a pessoa atende mais de uma, ou o ambiente, para "Homologação" não ser confundido com produção. Nome e linha cortam com reticências quando não cabem, e na coluna de ícones os dois somem com o resto do texto. Com ela a marca fica na altura do controle grande, aberta ou encolhida, para a navegação embaixo não pular quando a barra muda de largura.

<SidebarBrand mark={<img src="/logo.svg" alt="" />} description="Padaria Pão Quente">
  RivoCode
</SidebarBrand>

O submenu abre onde a pessoa está

SidebarMenuSub nasce aberto quando algum SidebarMenuItem de dentro tem active, e abre sozinho quando a navegação chega num filho. Quem entra por um link direto numa página de segundo nível vê o grupo aberto e o item marcado, e não um grupo fechado que esconde onde ela está. Fechar continua sendo um clique no título.

<SidebarMenuSub label="Cadastros">
  <SidebarMenuItem href="/clientes" active={path === "/clientes"}>
    Clientes
  </SidebarMenuItem>
</SidebarMenuSub>

defaultOpen passado vence a página ativa, e active no próprio submenu vale quando o filho ativo não é um SidebarMenuItem direto. Para guardar o aberto em outro lugar, open e onOpenChange: com open, a página ativa não abre nada sozinha.

title e label dizem coisas diferentes

Quatro peças da família recebem um texto, e dois nomes de prop dão conta dos quatro porque são quatro papéis:

  • Sidebar tem title: o título que só o leitor de tela ouve, no celular, onde a barra vira folha e perde o contexto. É o mesmo papel (e o mesmo nome) de CalendarPanel e Command.
  • SidebarGroup tem label: o cabeçalho visível de um grupo de itens, como em MenuGroup e nos grupos do Command.
  • SidebarInput tem label: o nome acessível de um campo sem rótulo visível, como em Editable, Splitter e Progress.
  • SidebarMenuSub tem label: o texto da própria linha, como em Tree e nos itens do Command.

Vale a pena saber disso ao procurar a prop: o nome segue o papel, e não a peça.

O SidebarMenuItem é um <a href> por padrão. Num app com router, o clique recarregaria a página inteira: passe o link do router pelo render, e o item continua com o desenho, o aria-current do active e o fechar da folha no celular.

import { NavLink } from 'react-router'

<SidebarMenuItem render={<NavLink to="/relatorios" />} active icon={<FileText />}>
  Relatórios
</SidebarMenuItem>

O Link do TanStack Router entra do mesmo jeito, e no Next é o Link de next/link: render={<Link href="/relatorios" />}.

Item que não navega - sair, trocar de conta, abrir um diálogo - entra com render={<button type="button" />}. A linha escreve a partir do começo (text-start), e não do meio como o botão faz por padrão, e a classe que vier no elemento do render soma com a da linha em vez de ser jogada fora.

O celular já vem resolvido

Nada disso precisa ser ligado na mão. Abaixo de 640px a barra vira folha, e a folha começa fechada: defaultOpen fala da coluna do desktop, onde aberta é o estado útil e a página continua inteira ao lado. No celular a mesma barra cobre tudo, e abrir sozinha ao carregar tapa justamente a tela que a pessoa veio ver.

O mesmo vale para o controlado. open e onOpenChange são o estado da mesa, e no celular não abrem a folha nem são chamados por ela: guardar open aberto num cookie não cobre a tela do celular ao carregar, e fechar a folha não grava fechado no estado da mesa. A folha tem estado próprio, e quem precisa controlá-la usa openMobile e onOpenMobileChange.

No celular, o className da Sidebar vai para a folha, e os outros atributos (role, data-*, aria-*) para o bloco dentro dela, sem apagar o papel de diálogo da folha.

Escolher um item também fecha a folha, que ali é a hora de sair da frente. Na mesa ela não cobre nada, então continua aberta. SidebarRail some no celular, porque arrastar uma borda de 1px com o dedo não é alvo.

Quando a aplicação precisa da mesma resposta, ela lê do mesmo lugar:

const { isMobile, open, collapsed, toggle, close } = useSidebar()

Fora de um SidebarProvider, o mesmo corte vem do useMobile():

import { useMobile } from '@rivocode/ui'

const isMobile = useMobile()

Os dois respondem pela mesma media query que a barra e o calendário usam. Escrever 640 de novo num canto da aplicação é como as duas metades da tela acabam discordando sobre o que é celular. Dentro do provider prefira useSidebar().isMobile, que evita um segundo assinante da mesma consulta.

No servidor os dois devolvem false, e não um palpite: a primeira pintura sai igual à do desktop e se corrige no primeiro efeito, porque errar para o lado estreito quebra o layout largo, e o contrário não.

Quando não usar

Menos de cinco destinos cabem numa barra de topo com links, ou em Tabs quando eles são vistas da mesma página, e sobra a largura inteira para o conteúdo. A barra lateral paga por si quando a lista cresce, ganha grupos e precisa de submenu.

No React Native

Não porta. A barra lateral é o esqueleto de navegação de uma tela larga; no celular quem faz esse papel é a tab bar e o drawer do router (Expo Router, React Navigation), que trazem gesto de borda, histórico e estado de aba de graça. Uma gaveta desenhada à mão por cima disso perde os três.

API

PropTipoPadrão
side0.4.0

De que lado da pagina ela mora.

"left" | "right""left"
title0.4.0

Titulo lido no celular, onde a barra vira folha.

string"Navegação"

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.