Home/Componentes/NavRail

NavRail

Padrão hollow-UI

Trilho de navegação vertical colapsável com suporte a drawer mobile, itens desabilitados e três variantes de estilo.

Preview

NavRail interativo — abra em tela grande para ver o comportamento colapsável. Em telas menores, use o botão flutuante.

Aba ativa: Dashboard

Instalação

Via CLI hollow-UI

Instalação

Via CLI (Recomendado)

1. Inicializar (primeira vez)

npx @scmposs/hollow-ui init
npx @scmposs/hollow-ui setup

2. Adicionar componente

npx @scmposs/hollow-ui add nav-rail

Os comandos init e setup fazem o pré-setup (necessário apenas uma vez). Se você rodar add sem isso, a CLI executa o setup automaticamente.

Via NPM

Instalar pacote completo

npm install @scmposs/hollow-ui@latest

Instala todos os componentes como dependência do projeto.

Uso Básico

Definindo items e controlando o estado ativo

NavRail básico

import { useState } from "react";
import { NavRail, type NavRailItem } from "@scmposs/hollow-ui";
import { LayoutDashboard, Users, Settings } from "lucide-react";

const items: NavRailItem[] = [
  { id: "dashboard", label: "Dashboard", icon: LayoutDashboard },
  { id: "users",     label: "Usuários",  icon: Users },
  { id: "settings",  label: "Config.",   icon: Settings },
];

export function AppShell() {
  const [tab, setTab] = useState("dashboard");

  return (
    <div className="flex min-h-screen">
      <NavRail items={items} value={tab} onValueChange={setTab} />
      <main className="flex-1 p-6">{/* conteúdo */}</main>
    </div>
  );
}

Variantes

Três aparências disponíveis via prop variant

default

variant="default"

ghost

variant="ghost"

solid

variant="solid"

Variantes

<NavRail variant="default" items={items} value={tab} onValueChange={setTab} />
<NavRail variant="ghost"   items={items} value={tab} onValueChange={setTab} />
<NavRail variant="solid"   items={items} value={tab} onValueChange={setTab} />

Tamanhos

Controle a altura dos itens com a prop size

Tamanhos

<NavRail size="sm" items={items} value={tab} onValueChange={setTab} />
<NavRail size="md" items={items} value={tab} onValueChange={setTab} />
<NavRail size="lg" items={items} value={tab} onValueChange={setTab} />

Colapso Controlado

Controle o estado colapsado externamente via collapsed e onCollapsedChange

Controlled collapse

const [collapsed, setCollapsed] = useState(false);

<NavRail
  items={items}
  value={tab}
  onValueChange={setTab}
  collapsed={collapsed}
  onCollapsedChange={setCollapsed}
/>

Itens Desabilitados

Use disabled e disabledMessage para indicar funcionalidades indisponíveis

Item desabilitado

const items: NavRailItem[] = [
  { id: "dashboard", label: "Dashboard", icon: LayoutDashboard },
  {
    id: "admin",
    label: "Admin",
    icon: ShieldCheck,
    disabled: true,
    disabledMessage: "Somente para administradores",
  },
];

API do Componente

Propriedades disponíveis para NavRail e NavRailItem

NavRail

Prop	Tipo	Padrão	Descrição
items	NavRailItem[]	—	Lista de itens de navegação
value	string	—	Id do item ativo
onValueChange	(value: string) => void	—	Callback de mudança de aba
collapsed	boolean	undefined	Estado colapsado controlado
defaultCollapsed	boolean	false	Estado colapsado inicial (não controlado)
onCollapsedChange	(v: boolean) => void	—	Callback de colapso
variant	"default" \| "ghost" \| "solid"	"default"	Aparência do container
size	"sm" \| "md" \| "lg"	"md"	Altura dos itens
className	string	—	Classes extras para o container desktop

NavRailItem

Prop	Tipo	Padrão	Descrição
id	string	—	Identificador único do item
label	string	—	Texto exibido ao expandir
icon	React.ElementType	—	Ícone Lucide ou qualquer componente
disabled	boolean	false	Desabilita o item
disabledMessage	string	—	Tooltip exibido ao passar o mouse num item desabilitado

Exemplo Completo

Integração com conteúdo dinâmico por aba

AppShell.tsx

"use client";

import { useState } from "react";
import { NavRail, type NavRailItem } from "@scmposs/hollow-ui";
import {
  LayoutDashboard, Users, BarChart3,
  FileText, Settings, ShieldCheck,
} from "lucide-react";

const items: NavRailItem[] = [
  { id: "dashboard",   label: "Dashboard",    icon: LayoutDashboard },
  { id: "users",       label: "Usuários",     icon: Users },
  { id: "reports",     label: "Relatórios",   icon: BarChart3 },
  { id: "documents",   label: "Documentos",   icon: FileText },
  {
    id: "permissions",
    label: "Permissões",
    icon: ShieldCheck,
    disabled: true,
    disabledMessage: "Em breve",
  },
  { id: "settings",    label: "Configurações", icon: Settings },
];

const views: Record<string, React.ReactNode> = {
  dashboard:   <div>Dashboard</div>,
  users:       <div>Usuários</div>,
  reports:     <div>Relatórios</div>,
  documents:   <div>Documentos</div>,
  settings:    <div>Configurações</div>,
};

export function AppShell() {
  const [tab, setTab] = useState("dashboard");

  return (
    <div className="flex min-h-screen bg-background">
      <NavRail
        items={items}
        value={tab}
        onValueChange={setTab}
        variant="default"
        size="md"
      />
      <main className="flex-1 p-6 overflow-auto">
        {views[tab] ?? <div>Selecione uma aba</div>}
      </main>
    </div>
  );
}