Componentnavigation

Navegação principal de um site ou de uma aplicação: uma linha de entradas em que umas são links e outras abrem um painel de links. Composto sobre Base UI Navigation Menu, com uma única superfície flutuante que muda de forma ao passar de um gatilho para o outro em vez de fechar um popup e abrir outro. O painel é navegação, não menu: os links continuam links, alcançáveis por Tab.

Instalação

npx up-web-ds add navigation-menu

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

Preview

Basic

Default

With Descriptions

Simple Links

All states

Basic

Default

With Descriptions

Simple Links

Usage

@/components/navigation-menu

import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
} from '@/components/navigation-menu'

Navigation Menu

1
2
3
4
5
6
7
8
9
10
11<NavigationMenu aria-label="Navegação principal">
  <NavigationMenuList>
    <NavigationMenuItem>
      <NavigationMenuTrigger>Catálogo</NavigationMenuTrigger>
      <NavigationMenuContent>
        <NavigationMenuLink href="/preview">Primitives</NavigationMenuLink>
        <NavigationMenuLink href="/preview">Recipes</NavigationMenuLink>
      </NavigationMenuContent>
    </NavigationMenuItem>
  </NavigationMenuList>
</NavigationMenu>

Props

Props de NavigationMenu
Prop	Type	Default	Description
actionsRef	`React.RefObject<NavigationMenuRootActions \| null>`	sem valor padrão	A ref to imperative actions.
align	`Align`	`'start'`	How to align the popup relative to the specified side.
className	`string \| ((state: NavigationMenuRootState) => 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.
closeDelay	`number`	`50`	How long to wait before closing the navigation popup. Specified in milliseconds.
defaultValue	`any`	`null`	The uncontrolled value of the item that should be initially selected. To render a controlled navigation menu, use the `value` prop instead.
delay	`number`	`50`	How long to wait before opening the navigation popup. Specified in milliseconds.
onOpenChangeComplete	`((open: boolean) => void)`	sem valor padrão	Event handler called after any animations complete when the navigation menu is closed.
onValueChange	`((value: any, eventDetails: NavigationMenuRoot.ChangeEventDetails) => void)`	sem valor padrão	Callback fired when the value changes.
orientation	`"horizontal" \| "vertical"`	`'horizontal'`	The orientation of the navigation menu.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, NavigationMenuRootState>`	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: NavigationMenuRootState) => 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.
value	`any`	`null`	The controlled value of the navigation menu item that should be currently open. When non-nullish, the menu will be open. When nullish, the menu will be closed. To render an uncontrolled navigation menu, use the `defaultValue` prop instead.

Estende NavigationMenuPrimitive.Root.Props & Pick<NavigationMenuPrimitive.Positioner.Props, 'align'>. Aceita também os atributos padrão de um elemento React (275 não listados).

NavigationMenuList

Props de NavigationMenuList
Prop	Type	Default	Description
className	`string \| ((state: NavigationMenuListState) => 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.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, NavigationMenuListState>`	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: NavigationMenuListState) => 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 NavigationMenuPrimitive.List.Props. Aceita também os atributos padrão de um elemento React (275 não listados).

NavigationMenuItem

Props de NavigationMenuItem
Prop	Type	Default	Description
className	`string \| ((state: NavigationMenuItemState) => 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.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, NavigationMenuItemState>`	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: NavigationMenuItemState) => 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.
value	`any`	sem valor padrão	A unique value that identifies this navigation menu item. If no value is provided, a unique ID will be generated automatically. Use when controlling the navigation menu programmatically.

Estende NavigationMenuPrimitive.Item.Props. Aceita também os atributos padrão de um elemento React (275 não listados).

NavigationMenuTrigger

Props de NavigationMenuTrigger
Prop	Type	Default	Description
className	`string \| ((state: NavigationMenuTriggerState) => 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.
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, NavigationMenuTriggerState>`	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: NavigationMenuTriggerState) => 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 NavigationMenuPrimitive.Trigger.Props. Aceita também os atributos padrão de um elemento React (285 não listados).

NavigationMenuContent

Props de NavigationMenuContent
Prop	Type	Default	Description
className	`string \| ((state: NavigationMenuContentState) => 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.
keepMounted	`boolean`	`false`	Whether to keep the content mounted in the DOM while the popup is closed. Ensures the content is present during server-side rendering for web crawlers.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, NavigationMenuContentState>`	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: NavigationMenuContentState) => 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 NavigationMenuPrimitive.Content.Props. Aceita também os atributos padrão de um elemento React (275 não listados).

NavigationMenuLink

Props de NavigationMenuLink
Prop	Type	Default	Description
active	`boolean`	`false`	Whether the link is the currently active page.
className	`string \| ((state: NavigationMenuLinkState) => 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.
closeOnClick	`boolean`	`false`	Whether to close the navigation menu when the link is clicked.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>, NavigationMenuLinkState>`	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: NavigationMenuLinkState) => 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 NavigationMenuPrimitive.Link.Props. Aceita também os atributos padrão de um elemento React (283 não listados).

Composition

A raiz renderiza sozinha a superfície flutuante; cada item é um gatilho com o seu painel, ou um link direto na linha.

Composição de NavigationMenu

NavigationMenu

NavigationMenu
- NavigationMenuList
  - NavigationMenuItem
    - NavigationMenuTrigger
    - NavigationMenuContent
      - NavigationMenuLink
  - NavigationMenuItem
    - NavigationMenuLink

Metadata

Notas de acessibilidade

Teclado verificado por teste e em navegador: as entradas são um grupo com foco itinerante, ArrowLeft e ArrowRight andam entre gatilhos e links da linha, Enter e ArrowDown abrem o painel do gatilho e levam o foco ao primeiro link; dentro do painel, Tab e as setas percorrem os links, e Tab depois do último segue para a próxima entrada da linha, que abre o seu painel na mesma superfície; Escape fecha devolvendo o foco ao gatilho; todo alvo mostra outline de foco. Leitor de tela verificado por teste: a raiz é um landmark nav nomeado por quem compõe — todos os examples passam aria-label, porque duas nav sem nome são indistinguíveis na lista de landmarks —, cada gatilho é um button com aria-expanded acompanhando o estado e aria-controls apontando para o painel aberto, o chevron é aria-hidden e fica fora do nome, os links do painel continuam links (sem papel menu nem menuitem) e o link da página atual carrega aria-current="page". Touch verificado em viewport de 375px com emulação de toque: gatilhos e links medem acima do piso de 24x24 da política de interação do Up Web DS, o toque abre o painel, a superfície cabe na largura disponível e a linha quebra em vez de empurrar a página para rolagem horizontal. Reduced motion verificado em navegador com prefers-reduced-motion: reduce, e a divisão é o ponto: o fade do painel e da superfície é preservado, encurtado para duration-fast, porque é ele que o Base UI observa para desmontar; o escalonamento de entrada, o deslize lateral entre painéis e o deslocamento da superfície entre gatilhos saem; o chevron perde o tween e continua chegando a 180deg, porque o ângulo é estado. Timing: o upstream usava 0.35s e 300ms fora da escala; a revisão escolheu duration-slow para a superfície que muda de forma e viaja — o mesmo vocabulário do Sheet e do Sidebar — e duration-default para o chevron, como no Accordion e no Collapsible.

Classificação

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

Origem e distribuição

Fonte: shadcn registry / navigation-menu
Licença: MIT
URL: https://ui.shadcn.com/r/styles/base-vega/navigation-menu.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: chevron-down
Construído sobre: Nenhum
Usado por: Nenhum ainda