Header navigation components

Q: What shape does the `items` prop expect?

HeaderNavigationBase takes items as an array of nav objects. Each one needs a label and an href, and can optionally carry an icon component, a badge node, a current boolean to force the active state, and a nested items array of sub-items for the second tier. The desktop header only renders each item's label; icon and badge show up in the mobile drawer.

Q: How do I mark the current page as active?

Pass the current path to the activeUrl prop and the header derives the active item for you: an item matches when its href equals activeUrl exactly, or when activeUrl starts with href + "/" so nested routes keep the parent highlighted. The one exception is a root href of "/", which is excluded from the prefix rule and only ever matches exactly — otherwise it would stay highlighted on every page. To override the match for one item, set current on that item.

Q: How do I add a second row of navigation?

There are two ways. Either nest an items array inside the top-level item that should own the second tier — it renders automatically when that item is active — or pass a separate subItems array to HeaderNavigationBase to control the second row directly. The secondary row is only rendered when there is at least one sub-item.

Q: Can I render the sub navigation as tabs instead of buttons?

Yes. The secondaryType prop accepts "buttons" (the default, which renders NavButton pills) and "tabs", which renders the sub-items as underline tabs using the Tabs and TabList components. The tabs only receive each sub-item's label, not its href, so handle navigation yourself if you use "tabs".

Q: How do I replace the buttons on the right side of the header?

Pass your own markup to the actions prop. When it is provided the built-in actions — the search, settings and notification NavButtons plus DropdownAccountButton — are skipped entirely, so you are responsible for rendering everything on that side.

Q: How do I center the navigation items?

Set centered to true. It defaults to false, which pins the nav items next to the logo; when enabled, the logo and actions each take equal space so the nav sits in the middle. Note that in the centered layout the search input in the buttons-style secondary row is not rendered.

Q: Is the header navigation responsive?

Yes. The full header is hidden below the lg breakpoint, and MobileNavigationHeader renders a compact bar with a menu button that opens a dismissable React Aria modal drawer. The drawer reuses the same items array through NavList and adds a search input, Support, Settings and Open in browser links, and a NavAccountCard. activeUrl is not passed to the drawer's NavList, so items there are not highlighted as active unless you add it.

FREE

Free and open-source React header navigation components built for modern applications and websites. These header navigations are built using React Aria and styled with Tailwind CSS.

Installation

You can add this header navigation component using our CLI or manually:

CLI

Manual

npx untitledui@latest add header-navigation

Below are examples and variations of this header navigation component:

Simple

Preview

Code

Dual-tier

Preview

Code

API reference

FeaturedCardCookiePreferences

Import FeaturedCardCookiePreferences from @/components/application/app-navigation/base-components/featured-cards. Renders a <div> element.

FeaturedCardCookiePreferences props
Prop	Type	Default	Description
`title`* (required)	`string`	—	Heading shown at the top of the card.
`description`* (required)	`ReactNode`	—	Supporting content shown below the heading. Usually a short line of body text, but any node is allowed, such as the step list and project list rendered by the onboarding and projects cards.
`confirmLabel`* (required)	`string`	—	Label for the card's primary action button.
`onDismiss`* (required)	`() => void`	—	Handler called when the user dismisses the card, from the close button in the top right corner or from the card's dismiss action.
`onConfirm`* (required)	`() => void`	—	Handler called when the user presses the card's primary action button.
`className`	`string`	—	Additional CSS class names to merge into the card's outer container.

FeaturedCardCurrentProjects

Import FeaturedCardCurrentProjects from @/components/application/app-navigation/base-components/featured-cards. Renders a <div> element.

FeaturedCardCurrentProjects props
Prop	Type	Default	Description
`title`* (required)	`string`	—	Heading shown at the top of the card.
`description`* (required)	`ReactNode`	—	Supporting content shown below the heading. Usually a short line of body text, but any node is allowed, such as the step list and project list rendered by the onboarding and projects cards.
`confirmLabel`* (required)	`string`	—	Label for the card's primary action button.
`onDismiss`* (required)	`() => void`	—	Handler called when the user dismisses the card, from the close button in the top right corner or from the card's dismiss action.
`onConfirm`* (required)	`() => void`	—	Handler called when the user presses the card's primary action button.
`className`	`string`	`"relative flex flex-col gap-4 rounded-xl bg-primary p-4 ring-1 ring-secondary ring-inset"`	Additional CSS class names to merge into the card's outer container.

FeaturedCardEventCTA

Import FeaturedCardEventCTA from @/components/application/app-navigation/base-components/featured-cards. Renders a <div> element.

FeaturedCardEventCTA props
Prop	Type	Default	Description
`title`* (required)	`string`	—	Heading shown at the top of the card.
`description`* (required)	`ReactNode`	—	Supporting content shown below the heading. Usually a short line of body text, but any node is allowed, such as the step list and project list rendered by the onboarding and projects cards.
`confirmLabel`* (required)	`string`	—	Label for the card's primary action button.
`onDismiss`* (required)	`() => void`	—	Handler called when the user dismisses the card, from the close button in the top right corner or from the card's dismiss action.
`onConfirm`* (required)	`() => void`	—	Handler called when the user presses the card's primary action button.
`className`	`string`	`"relative flex flex-col gap-4 rounded-xl bg-primary p-4 ring-1 ring-secondary ring-inset"`	Additional CSS class names to merge into the card's outer container.
`badge`	`string`	—	Text for the status badge with a dot shown beside the heading, such as a live indicator for the event. Omit it to hide the badge.

FeaturedCardFreeTrialCTA

Import FeaturedCardFreeTrialCTA from @/components/application/app-navigation/base-components/featured-cards. Renders a <div> element.

FeaturedCardFreeTrialCTA props
Prop	Type	Default	Description
`title`* (required)	`string`	—	Heading shown at the top of the card.
`onDismiss`* (required)	`() => void`	—	Handler called when the user dismisses the card, from the close button in the top right corner or from the card's dismiss action.
`confirmLabel`* (required)	`string`	—	Label for the card's primary action button.
`onConfirm`* (required)	`() => void`	—	Handler called when the user presses the card's primary action button.
`supportingText`* (required)	`string`	—	Muted text shown opposite the heading, typically how much of the trial is left.
`progress`* (required)	`number`	—	Trial progress percentage, from 0 to 100, shown in the progress bar below the heading.
`className`	`string`	`"relative flex flex-col gap-4 rounded-xl bg-primary p-4 ring-1 ring-secondary ring-inset"`	Additional CSS class names to merge into the card's outer container.

FeaturedCardImage

Import FeaturedCardImage from @/components/application/app-navigation/base-components/featured-cards. Renders a <div> element.

FeaturedCardImage props
Prop	Type	Default	Description
`title`* (required)	`string`	—	Heading shown at the top of the card.
`description`* (required)	`ReactNode`	—	Supporting content shown below the heading. Usually a short line of body text, but any node is allowed, such as the step list and project list rendered by the onboarding and projects cards.
`confirmLabel`* (required)	`string`	—	Label for the card's primary action button.
`onDismiss`* (required)	`() => void`	—	Handler called when the user dismisses the card, from the close button in the top right corner or from the card's dismiss action.
`onConfirm`* (required)	`() => void`	—	Handler called when the user presses the card's primary action button.
`imageSrc`* (required)	`string`	—	Source URL for the thumbnail shown between the text and the actions, overlaid with a play icon.
`className`	`string`	—	Additional CSS class names to merge into the card's outer container.

FeaturedCardMessage

Import FeaturedCardMessage from @/components/application/app-navigation/base-components/featured-cards. Renders a <div> element.

FeaturedCardMessage props
Prop	Type	Default	Description
`title`* (required)	`string`	—	Heading shown at the top of the card.
`description`* (required)	`ReactNode`	—	Supporting content shown below the heading. Usually a short line of body text, but any node is allowed, such as the step list and project list rendered by the onboarding and projects cards.
`confirmLabel`* (required)	`string`	—	Label for the card's primary action button.
`onDismiss`* (required)	`() => void`	—	Handler called when the user dismisses the card, from the close button in the top right corner or from the card's dismiss action.
`onConfirm`* (required)	`() => void`	—	Handler called when the user presses the card's primary action button.
`supportingText`* (required)	`string`	—	Muted text shown next to the sender's name, such as how long ago the message arrived.
`className`	`string`	`"relative flex flex-col gap-4 rounded-xl bg-primary p-4 ring-1 ring-secondary ring-inset"`	Additional CSS class names to merge into the card's outer container.

FeaturedCardOnboardingSteps

Import FeaturedCardOnboardingSteps from @/components/application/app-navigation/base-components/featured-cards. Renders a <div> element.

FeaturedCardOnboardingSteps props
Prop	Type	Default	Description
`title`* (required)	`string`	—	Heading shown at the top of the card.
`description`* (required)	`ReactNode`	—	Supporting content shown below the heading. Usually a short line of body text, but any node is allowed, such as the step list and project list rendered by the onboarding and projects cards.
`confirmLabel`* (required)	`string`	—	Label for the card's primary action button.
`onDismiss`* (required)	`() => void`	—	Handler called when the user dismisses the card, from the close button in the top right corner or from the card's dismiss action.
`onConfirm`* (required)	`() => void`	—	Handler called when the user presses the card's primary action button.
`supportingText`* (required)	`string`	—	Muted text shown opposite the heading, typically the current step count such as "Step 3 of 4".
`progress`* (required)	`number`	—	Onboarding completion percentage, from 0 to 100, shown in the progress bar below the heading.
`className`	`string`	`"relative flex flex-col gap-4 rounded-xl bg-primary p-4 ring-1 ring-secondary ring-inset"`	Additional CSS class names to merge into the card's outer container.

FeaturedCardQRCode

Import FeaturedCardQRCode from @/components/application/app-navigation/base-components/featured-cards. Renders a <div> element.

FeaturedCardQRCode props
Prop	Type	Default	Description
`title`* (required)	`string`	—	Heading shown at the top of the card.
`description`* (required)	`ReactNode`	—	Supporting content shown below the heading. Usually a short line of body text, but any node is allowed, such as the step list and project list rendered by the onboarding and projects cards.
`confirmLabel`* (required)	`string`	—	Label for the card's primary action button.
`onDismiss`* (required)	`() => void`	—	Handler called when the user dismisses the card, from the close button in the top right corner or from the card's dismiss action.
`onConfirm`* (required)	`() => void`	—	Handler called when the user presses the card's primary action button.
`className`	`string`	`"relative flex flex-col gap-4 rounded-xl bg-primary p-4 ring-1 ring-secondary ring-inset"`	Additional CSS class names to merge into the card's outer container.

FeaturedCardReferralLink

Import FeaturedCardReferralLink from @/components/application/app-navigation/base-components/featured-cards. Renders a <div> element.

FeaturedCardReferralLink props
Prop	Type	Default	Description
`title`* (required)	`string`	—	Heading shown at the top of the card.
`description`* (required)	`ReactNode`	—	Supporting content shown below the heading. Usually a short line of body text, but any node is allowed, such as the step list and project list rendered by the onboarding and projects cards.
`onDismiss`* (required)	`() => void`	—	Handler called when the user dismisses the card, from the close button in the top right corner or from the card's dismiss action.
`className`	`string`	—	Additional CSS class names to merge into the card's outer container.

FeaturedCardSupportCTA

Import FeaturedCardSupportCTA from @/components/application/app-navigation/base-components/featured-cards. Renders a <div> element.

FeaturedCardSupportCTA props
Prop	Type	Default	Description
`title`* (required)	`string`	—	Heading shown at the top of the card.
`description`* (required)	`ReactNode`	—	Supporting content shown below the heading. Usually a short line of body text, but any node is allowed, such as the step list and project list rendered by the onboarding and projects cards.
`confirmLabel`* (required)	`string`	—	Label for the card's primary action button.
`onDismiss`* (required)	`() => void`	—	Handler called when the user dismisses the card, from the close button in the top right corner or from the card's dismiss action.
`onConfirm`* (required)	`() => void`	—	Handler called when the user presses the card's primary action button.
`className`	`string`	`"relative flex flex-col gap-4 rounded-xl bg-primary p-4 ring-1 ring-secondary ring-inset"`	Additional CSS class names to merge into the card's outer container.
`badge`	`string`	—	Text for the status badge with a dot shown above the heading, such as the support team's availability. Omit it to hide the badge.

FeaturedCardUpgradeCTA

Import FeaturedCardUpgradeCTA from @/components/application/app-navigation/base-components/featured-cards. Renders a <div> element.

FeaturedCardUpgradeCTA props
Prop	Type	Default	Description
`title`* (required)	`string`	—	Heading shown at the top of the card.
`description`* (required)	`ReactNode`	—	Supporting content shown below the heading. Usually a short line of body text, but any node is allowed, such as the step list and project list rendered by the onboarding and projects cards.
`confirmLabel`* (required)	`string`	—	Label for the card's primary action button.
`onDismiss`* (required)	`() => void`	—	Handler called when the user dismisses the card, from the close button in the top right corner or from the card's dismiss action.
`onConfirm`* (required)	`() => void`	—	Handler called when the user presses the card's primary action button.
`icon`* (required)	`FC<HTMLAttributes<HTMLOrSVGElement>>`	—	Icon component rendered inside the featured icon above the heading.
`className`	`string`	`"relative flex flex-col gap-4 rounded-xl bg-primary p-4 ring-1 ring-secondary ring-inset"`	Additional CSS class names to merge into the card's outer container.
`badge`	`string`	—	Text for the small badge shown beside the heading, such as a discount label. Omit it to hide the badge.

HeaderNavigationBase

Import HeaderNavigationBase from @/components/application/app-navigation/header-navigation. Renders MobileNavigationHeader.

HeaderNavigationBase props
Prop	Type	Default	Description
`items`* (required)	`NavItem[]`	—	List of items to display.
`activeUrl`	`string`	—	URL of the currently active item.
`subItems`	`NavItem[]`	—	List of sub-items to display.
`hideBorder`	`boolean`	`false`	Whether to hide the bottom border.
`actions`	`ReactNode`	—	Replaces the entire right-side actions (icon buttons + account dropdown). When provided, the default actions are ignored.
`centered`	`boolean`	`false`	Centers the primary nav items between the logo and actions.
`secondaryType`	`"buttons""tabs"`	`"buttons"`	Controls how the secondary header renders sub-items. "buttons" — NavButton pills (default). "tabs" — Underline tabs.

MobileNavigationHeader

Import MobileNavigationHeader from @/components/application/app-navigation/base-components/mobile-header. Renders React Aria’s DialogTrigger — all of its props are supported.

MobileNavigationHeader props
Prop	Type	Default	Description
`children`	`ReactNode`	—	—

NavAccountCard

Import NavAccountCard from @/components/application/app-navigation/base-components/nav-account-card. Renders a <div> element.

NavAccountCard props
Prop	Type	Default	Description
`popoverPlacement`	`"bottom""bottom left""bottom right""bottom start""bottom end""top""top left""top right""top start""top end""left""left top""left bottom""start"` +8 moreShow fewer `"start top""start bottom""right""right top""right bottom""end""end top""end bottom"`	"right bottom" from the `lg` breakpoint up, "top right" below it	Where the account menu opens relative to the card.
`selectedAccountId`	`string`	`"caitlyn"`	The `id` of the account from `items` to show in the card. Nothing is rendered if no item matches, and a warning is logged.
`items`	`NavAccountType[]`	`placeholderAccounts`	The accounts the card can display. The one matching `selectedAccountId` fills the card, and the list is handed to the account menu.
`avatarRounded`	`boolean`	—	Whether the account avatar is a circle. Pass `false` for a rounded square.

NavAccountMenu

Import NavAccountMenu from @/components/application/app-navigation/base-components/nav-account-card. Renders React Aria’s Dialog — all of its props are supported.

NavAccountMenu props
Prop	Type	Default	Description
`accounts`	`NavAccountType[]`	—	The accounts offered in the "Switch account" section. Accepted for parity with `NavAccountCard`, which passes its own list down; the menu itself always renders the built-in demo accounts.
`selectedAccountId`	`string`	`"olivia"`	The `id` of the account to present as the current one — its row is highlighted and its radio button is selected.

Props from React Aria Components (11)

NavAccountMenu inherited props
Prop	Type	Default	Description
`children`	`ReactNode \| ((opts: DialogRenderProps) => ReactNode)`	—	Children of the dialog. A function may be provided to access a function to close the dialog.
`id`	`string`	—	The element's unique identifier.
`slot`	`string \| null`	—	A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.
`className`	`string`	—	The CSS className for the element.
`render`	`DOMRenderFunction<"section", undefined>`	—	Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components.Requirements: You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). Only a single root DOM element can be rendered (no fragments). You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
`style`	`CSSProperties`	—	The inline style for the element.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`role`	`"dialog""alertdialog"`	`"dialog"`	The accessibility role for the dialog.

Also accepts the global HTML attributes (dir, lang, hidden, inert, translate), all standard React DOM event handlers.

NavButton

Import NavButton from @/components/application/app-navigation/base-components/nav-button. Renders Tooltip.

NavButton props
Prop	Type	Default	Description
`open`	`boolean`	—	Whether the collapsible nav item is open.
`href`	`string`	—	URL to navigate to when the button is clicked.
`label`	`string`	—	Label text for the button.
`icon`	`FC<{ className?: string; }>`	—	Icon component to display.
`current`	`boolean`	—	Whether the button is currently active.
`onClick`	`MouseEventHandler`	—	Handler for click events.
`className`	`string`	—	Additional CSS classes to apply to the button.
`tooltipPlacement`	`"top""right""bottom""left"`	`"right"`	Placement of the tooltip.
`children`	`ReactNode`	—	Content to display.

NavItemBase

Import NavItemBase from @/components/application/app-navigation/base-components/nav-item. Renders React Aria’s Link — all of its props are supported.

NavItemBase props
Prop	Type	Default	Description
`type`* (required)	`"collapsible""link""collapsible-child"`	—	Type of the nav item.
`icon`	`FC<HTMLAttributes<HTMLOrSVGElement>>`	—	Icon component to display.
`badge`	`ReactNode`	—	Badge to display.
`current`	`boolean`	—	Whether the nav item is currently active.
`truncate`	`boolean`	`true`	Whether to truncate the label text.
`onClick`	`MouseEventHandler`	—	Handler for click events.
`children`	`ReactNode`	—	Content to display.

NavList

Import NavList from @/components/application/app-navigation/base-components/nav-list. Renders a <ul> element.

NavList props
Prop	Type	Default	Description
`items`* (required)	`(NavItemType \| NavItemDividerType)[]`	—	List of items to display.
`activeUrl`	`string`	—	URL of the currently active item.
`className`	`string`	—	Additional CSS classes to apply to the list.

FAQs

Please refer to our frequently asked questions page for more.

HeaderNavigationBase takes items as an array of nav objects. Each one needs a label and an href, and can optionally carry an icon component, a badge node, a current boolean to force the active state, and a nested items array of sub-items for the second tier. The desktop header only renders each item's label; icon and badge show up in the mobile drawer.

Pass the current path to the activeUrl prop and the header derives the active item for you: an item matches when its href equals activeUrl exactly, or when activeUrl starts with href + "/" so nested routes keep the parent highlighted. The one exception is a root href of "/", which is excluded from the prefix rule and only ever matches exactly — otherwise it would stay highlighted on every page. To override the match for one item, set current on that item.

There are two ways. Either nest an items array inside the top-level item that should own the second tier — it renders automatically when that item is active — or pass a separate subItems array to HeaderNavigationBase to control the second row directly. The secondary row is only rendered when there is at least one sub-item.

Yes. The secondaryType prop accepts "buttons" (the default, which renders NavButton pills) and "tabs", which renders the sub-items as underline tabs using the Tabs and TabList components. The tabs only receive each sub-item's label, not its href, so handle navigation yourself if you use "tabs".

Pass your own markup to the actions prop. When it is provided the built-in actions — the search, settings and notification NavButtons plus DropdownAccountButton — are skipped entirely, so you are responsible for rendering everything on that side.

Set centered to true. It defaults to false, which pins the nav items next to the logo; when enabled, the logo and actions each take equal space so the nav sits in the middle. Note that in the centered layout the search input in the buttons-style secondary row is not rendered.

Yes. The full header is hidden below the lg breakpoint, and MobileNavigationHeader renders a compact bar with a menu button that opens a dismissable React Aria modal drawer. The drawer reuses the same items array through NavList and adds a search input, Support, Settings and Open in browser links, and a NavAccountCard. activeUrl is not passed to the drawer's NavList, so items there are not highlighted as active unless you add it.

Gradient pickers Image pickers

Header navigation components

Header navigation example

Header navigation example

Installation

Header navigation examples

Simple

Simple

Dual-tier

Dual-tier

API reference

FeaturedCardCurrentProjects

FeaturedCardEventCTA

FeaturedCardFreeTrialCTA

FeaturedCardImage

FeaturedCardMessage

FeaturedCardOnboardingSteps

FeaturedCardQRCode

FeaturedCardReferralLink

FeaturedCardSupportCTA

FeaturedCardUpgradeCTA

HeaderNavigationBase

MobileNavigationHeader

NavAccountCard

NavAccountMenu

NavButton

NavItemBase

NavList

FAQs