On this page
Nav
Navigation components for building various types of navigation interfaces, including tabs and pills.
Playground
Experiment with the Nav component by adjusting the props below. Try switching between explicit active state control and internal management to see how the component behaves differently.
Interactive Playground
Controls
Preview
Code
<Nav.Root>
<Nav.Item>
<Nav.Link href="#nav-link-0" isActive={true}>Nav Item 1</Nav.Link>
</Nav.Item>
<Nav.Item>
<Nav.Link href="#nav-link-1" isActive={false}>Nav Item 2</Nav.Link>
</Nav.Item>
<Nav.Item>
<Nav.Link href="#nav-link-2" isActive={false}>Nav Item 3</Nav.Link>
</Nav.Item>
</Nav.Root>
Basic Example
The default navigation component uses a <ul> with <li> items containing <a> links.
<Nav.Root>
<Nav.Item>
<Nav.Link href="#!" isActive={true}>Active</Nav.Link>
</Nav.Item>
<Nav.Item>
<Nav.Link href="#!">Link</Nav.Link>
</Nav.Item>
<Nav.Item>
<Nav.Link href="#!">Another Link</Nav.Link>
</Nav.Item>
<Nav.Item>
<Nav.Link href="#!" isDisabled={true}>Disabled</Nav.Link>
</Nav.Item>
</Nav.Root>
Pills
Use the itemStyle="pills" prop to create a navigation with pills styling.
<Nav.Root itemStyle="pills">
<Nav.Item>
<Nav.Link href="#!" isActive={true}>Active</Nav.Link>
</Nav.Item>
<Nav.Item>
<Nav.Link href="#!">Link</Nav.Link>
</Nav.Item>
<Nav.Item>
<Nav.Link href="#!">Another Link</Nav.Link>
</Nav.Item>
<Nav.Item>
<Nav.Link href="#!" isDisabled={true}>Disabled</Nav.Link>
</Nav.Item>
</Nav.Root>
Tabs
Use the itemStyle="tabs" prop to create a navigation with tabs styling.
<Nav.Root itemStyle="tabs">
<Nav.Item>
<Nav.Link href="#!" isActive={true}>Active</Nav.Link>
</Nav.Item>
<Nav.Item>
<Nav.Link href="#!">Link</Nav.Link>
</Nav.Item>
<Nav.Item>
<Nav.Link href="#!">Another Link</Nav.Link>
</Nav.Item>
<Nav.Item>
<Nav.Link href="#!" isDisabled={true}>Disabled</Nav.Link>
</Nav.Item>
</Nav.Root>
Vertical Nav
Use the verticalBreakpoint prop to create a vertically stacked navigation. Set it to "xs" to make it always vertical.
<Nav.Root verticalBreakpoint="xs">
<Nav.Item>
<Nav.Link href="#!" isActive={true}>Active</Nav.Link>
</Nav.Item>
<Nav.Item>
<Nav.Link href="#!">Link</Nav.Link>
</Nav.Item>
<Nav.Item>
<Nav.Link href="#!">Another Link</Nav.Link>
</Nav.Item>
<Nav.Item>
<Nav.Link href="#!" isDisabled={true}>Disabled</Nav.Link>
</Nav.Item>
</Nav.Root>
Fill and Justify
Force your .nav's contents to extend the full available width with one of two options:
Fill
Use itemLayout="fill" to proportionately fill all available space.
<Nav.Root itemLayout="fill">
<Nav.Item>
<Nav.Link href="#!" isActive={true}>Active</Nav.Link>
</Nav.Item>
<Nav.Item>
<Nav.Link href="#!">Link</Nav.Link>
</Nav.Item>
<Nav.Item>
<Nav.Link href="#!">Another Link</Nav.Link>
</Nav.Item>
<Nav.Item>
<Nav.Link href="#!" isDisabled={true}>Disabled</Nav.Link>
</Nav.Item>
</Nav.Root>
Justified
Use itemLayout="justified" for equal-width elements.
<Nav.Root itemLayout="justified">
<Nav.Item>
<Nav.Link href="#!" isActive={true}>Active</Nav.Link>
</Nav.Item>
<Nav.Item>
<Nav.Link href="#!">Link</Nav.Link>
</Nav.Item>
<Nav.Item>
<Nav.Link href="#!">Another Link</Nav.Link>
</Nav.Item>
<Nav.Item>
<Nav.Link href="#!" isDisabled={true}>Disabled</Nav.Link>
</Nav.Item>
</Nav.Root>
Horizontal Alignment
Use the horizontalAlignment prop to change the horizontal alignment of your nav. Default is "start", but you can use "center" or
"end".
<!-- Default (start) -->
<Nav.Root>
<Nav.Item><Nav.Link href="#!">Default</Nav.Link></Nav.Item>
</Nav.Root>
<!-- Center aligned -->
<Nav.Root horizontalAlignment="center">
<Nav.Item><Nav.Link href="#!">Center</Nav.Link></Nav.Item>
</Nav.Root>
<!-- End aligned -->
<Nav.Root horizontalAlignment="end">
<Nav.Item><Nav.Link href="#!">End</Nav.Link></Nav.Item>
</Nav.Root>
Different Element Types
The Nav component can be rendered as different HTML elements using the elementType prop. The default is "ul",
but you can also use "ol" or "nav".
<!-- Default (UL) -->
<Nav.Root>
<Nav.Item><Nav.Link href="#!">Link</Nav.Link></Nav.Item>
</Nav.Root>
<!-- As OL -->
<Nav.Root elementType="ol">
<Nav.Item><Nav.Link href="#!">Link</Nav.Link></Nav.Item>
</Nav.Root>
<!-- As NAV -->
<Nav.Root elementType="nav">
<Nav.Link href="#!">Link</Nav.Link>
</Nav.Root>
Active State Management
The Nav component supports two modes for managing active states:
Explicit Control
When you provide the isActive prop, you have full control over the active state. This is useful when integrating with routing libraries
or when you need precise control.
Internal Management
When you don't provide the isActive prop (or set it to undefined), the component manages the active state
internally. Clicking a link will make it active and deactivate others in the same nav.
⚠️ NOTE: In order for the internal state management to work properly, ensure that the href prop is set to a unique value
for each.
<!-- Explicit Active State Control -->
<Nav.Root>
<Nav.Item>
<Nav.Link href="#!" isActive={true}>Explicitly Active</Nav.Link>
</Nav.Item>
<Nav.Item>
<Nav.Link href="#!" isActive={false}>Explicitly Inactive</Nav.Link>
</Nav.Item>
</Nav.Root>
<!-- Internal Active State Management -->
<Nav.Root>
<Nav.Item>
<Nav.Link href="#nav-link-1">Click to Activate</Nav.Link>
</Nav.Item>
<Nav.Item>
<Nav.Link href="#nav-link-2">Another Link</Nav.Link>
</Nav.Item>
</Nav.Root>
Tabs with Content
For dynamic tabbed interfaces, use the Nav component with the Tab component. See the Tab documentation for more details.
Accessibility and landmarks
Ordinary Nav.Root lists retain their native list semantics. Styling with itemStyle="tabs", "pills" or "underline" does not turn navigation links into a tab widget. In the navigation strip of Tab.Root, the root
defaults to role="tablist" for every style. Navigation inside a Tab.Pane retains ordinary semantics, although a Tab.NavLink there, or a bare Nav.Link with no Nav.Root inside that pane, still selects a pane of
its Tab.Root. A bare link's click is intercepted and its href is read as a pane ID, so even href="/settings" does not navigate; place links that should navigate under a Nav.Root inside the pane. A nested Tab.Root creates its own tab widget. Use the Tab components when links switch associated panels.
For an ordinary navigation landmark, wrap the list in a named <nav>, or use elementType="nav" with direct Nav.Link children. Do not put role="navigation" on a <ul> or <ol>.
<nav aria-label="Primary navigation">
<Nav.Root>
<Nav.Item><Nav.Link href="/home">Home</Nav.Link></Nav.Item>
<Nav.Item><Nav.Link href="/about">About</Nav.Link></Nav.Item>
</Nav.Root>
</nav>
Migration: selectors or accessibility queries that relied on the old list navigation role should target the native list or its <nav> wrapper. Explicit role values remain under your control; role={null} omits the root
role attribute, including inside Tab.Root. Root overrides other than tablist also disable inferred child
tab/presentation roles and tab-specific ARIA attributes; explicit child roles are honored instead. This changes semantics, not panel
selection behavior. If overriding roles, provide a coherent container and child structure. Selection does change in one case: a Nav.Link under a Nav.Root inside a Tab.Pane previously selected a pane and now follows its href, whatever the root role. Use Tab.NavLink to select panes from such a container. Automatic vertical
orientation is emitted only for tablists with verticalBreakpoint="xs". Responsive layouts do not infer a static orientation;
use ariaOrientation to supply a value that tracks your layout.
Within a Tab.Root tablist, links with tab semantics automatically select and focus the next/previous enabled tab with
Right/Down and Left/Up Arrow, wrapping at the ends; Home/End select the first/last enabled tab. Only the selected enabled tab is a tab
stop by default, falling back to the first enabled tab after mount when none is selected. Disabled links cannot activate. Tab links use aria-selected without aria-current; ordinary active navigation keeps aria-current="page". Explicit link roles are honored, and
non-tab roles opt out of managed tab behavior. Enabled links preserve explicit tabindex; explicit isActive still controls rendered selection and must be synchronized by the application when
controlling tabs. See Tab accessibility guidance for keyboard callbacks and pane lifecycle events.
Custom tab widgets outside Tab.Root must explicitly set role="tablist" on Nav.Root, role="presentation" on Nav.Item and role="tab" on Nav.Link, with associated panels, selection state and interaction
behavior managed by the consumer. Styling alone no longer supplies those semantics.
API Reference
Nav.Root Props
| Name | Type | Default | Description |
|---|---|---|---|
ariaOrientation | 'horizontal' | 'vertical' | - | Explicit ARIA orientation. A tablist infers 'vertical' only for verticalBreakpoint='xs'. Responsive breakpoints require explicit orientation tracking; ordinary navigation does not infer orientation. |
elementType | 'nav' | 'ol' | 'ul' | 'ul' | Element type to render |
class | string | - | Additional CSS classes to apply to the component |
elementRef | HTMLElement | null | null | Reference to the DOM element |
horizontalAlignment | 'start' | 'center' | 'end' | 'start' | Horizontal alignment for the nav items |
id | string | Auto-generated | Unique identifier for the nav |
itemLayout | 'fill' | 'justified' | - | Layout strategy for the nav items |
itemStyle | 'pills' | 'tabs' | 'underline' | - | Visual style for the nav items |
role | 'navigation' | 'tablist' | null | Auto-determined | Defaults to 'tablist' in a Tab.Root navigation strip, otherwise omitted. Explicit roles are honored; null omits the role attribute. Use 'navigation' only with elementType='nav', never on a ul or ol. |
verticalBreakpoint | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl' | - | Breakpoint at which the nav becomes vertical. 'xs' means always vertical. |
Nav.Item Props
| Name | Type | Default | Description |
|---|---|---|---|
class | string | - | Additional CSS classes to apply to the component |
elementRef | HTMLElement | null | null | Reference to the DOM element |
Nav.Link Props
| Name | Type | Default | Description |
|---|---|---|---|
class | string | - | Additional CSS classes to apply to the component |
elementRef | HTMLElement | null | null | Reference to the DOM element |
href | string | '#!' | URL for the link. The exclamation point is used to prevent auto-scrolling to the top of the page. |
id | string | Auto-generated | Unique identifier for the link |
isActive | boolean | undefined | undefined | Whether the link is active. When provided, overrides internal state management. When undefined, the component manages active state internally based on user interactions. |
isDisabled | boolean | false | Whether the link is disabled |
role | 'button' | 'tab' | Auto-determined | ARIA role for the link. Defaults to 'tab' in a tab strip; explicit roles are honored. |
CSS Classes
The component applies Bootstrap's nav classes based on the provided props:
nav- Base class for the Nav componentnav-item- Applied to Nav.Item componentsnav-link- Applied to Nav.Link componentsnav-pills- Applied when itemStyle="pills"nav-tabs- Applied when itemStyle="tabs"nav-underline- Applied when itemStyle="underline"nav-fill- Applied when itemLayout="fill"nav-justified- Applied when itemLayout="justified"flex-column- Applied when verticalBreakpoint="xs"flex-{breakpoint}-column- Applied for other verticalBreakpoint valuesjustify-content-center- Applied when horizontalAlignment="center"justify-content-end- Applied when horizontalAlignment="end"active- Applied to Nav.Link when isActive=truedisabled- Applied to Nav.Link when isDisabled=true