Sidebar
Tela de operação
Pedidos
Carregando a navegação
Com o link do router
render troca a âncora pelo link do router e mantém o desenho da linha. Estes três levam à demonstração.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:
SidebarInputvira o ícone da lupa, que abre a barra de volta. Um campo de texto de 3,5rem não aceita nem uma palavra.SidebarMenuSubvira um menu que salta ao lado, com os mesmos filhos. Indentar não cabe; esconder seria pior.SidebarGroupesconde o título. Sumir diz menos, mentir sobre o nome do grupo diz errado.SidebarMenuItemmostra 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:
Sidebartemtitle: 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) deCalendarPaneleCommand.SidebarGrouptemlabel: o cabeçalho visível de um grupo de itens, como emMenuGroupe nos grupos doCommand.SidebarInputtemlabel: o nome acessível de um campo sem rótulo visível, como emEditable,SplittereProgress.SidebarMenuSubtemlabel: o texto da própria linha, como emTreee nos itens doCommand.
Vale a pena saber disso ao procurar a prop: o nome segue o papel, e não a peça.
Com o link do router
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
| Prop | Tipo | Padrão |
|---|---|---|
side0.4.0De que lado da pagina ela mora. | "left" | "right" | "left" |
title0.4.0Titulo 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.