Navigation
Last Updated: September 2026Navigation items represent different destinations within the page or the applications. They let users trigger a navigation to the selected destination.
Source CodeAnatomy
link- 1Icon
- 2Label
Variants
linkDefault
Icon + label destination link.
Active
Highlights the current location.
Disabled
Unavailable destination styling.
Icon only
Omit label for compact rails; supply an accessible name on the host.
Sizes
linkNavigation items support 2 sizes: S and M.
Usage Guidelines
linkWhen to use
- •For sidebar, rail, or stacked app destinations.
- •When each destination needs an icon and short label.
- •To mark the current route with active.
When not to use
- •For inline body links — use Link.
- •For action menus — use Menu.
- •For primary page CTAs — use Button.
Stack items vertically and mark exactly one active route.
Don't mark multiple items active in the same nav group.
Keep labels short and destination-oriented.
Don't use NavigationItem for destructive commands — use Menu or Button.
Behaviors
linkStates
- •active applies accent background and foreground.
- •disabled uses disabled foreground and not-allowed cursor.
Polymorphic render
- •Defaults to an anchor; pass render for router links or buttons.
- •href and other anchor props pass through to the host.
Content Guidelines
linkLabels
- •Use destination nouns ('Appointments', 'Patients', 'Notes').
- •Match icon meaning to the label.
Accessibility
linkText & Labels
- •Provide label or aria-label — especially for icon-only items.
- •Ensure the active item is perceivable by more than color alone (background + text).
ARIA attributes
- •For current page, consider aria-current="page" on the active item host.
Keyboard Support
- •Tab → focus.
- •Enter → activate navigation.
WCAG Compliance Standards
FAQs
linkWhat is the page slug?
Registry slug is "navigation"; importPath is navigation/navigation-item.
Link vs NavigationItem?
Use NavigationItem for app chrome destinations. Use Link for inline or supportive links.
Can I use a router Link?
Yes — pass it through the render prop while keeping icon/label props.