ts
| Guidance | Practices |
|---|---|
| Do | Include a product logo and name in the heading slot to clearly identify the application. |
| Do | Limit primary navigation items to 5 or fewer for quick scanning and minimal cognitive load. |
| Don't | Avoid using TopNav to filter page content — use Tabs or filter controls instead. |
| Don't | Avoid deeply nested navigation hierarchies — keep menus to one level of depth. |
| Prop | Type | Description |
|---|---|---|
heading | ReactNode | Heading slot content (logo, brand) — positioned at the left edge of the nav bar. |
startContent | ReactNode | Start content slot for navigation items or breadcrumbs — positioned after the heading, left-aligned. |
centerContent | ReactNode | Center content slot (tabs, search bar, primary navigation) — when provided, switches the layout to a three-column CSS grid for true horizontal centering. |
endContent | ReactNode | End content slot for search, icons, or user profile — positioned at the right edge. |
label | string | Accessible label for the navigation landmark, applied as aria-label on the <nav> element. |
xstyle | StyleXStyles | StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}. |
| Prop | Type | Description |
|---|---|---|
logo | ReactNode | Logo element to display before the heading text. Can be an image, XDSNavIcon, or any ReactNode. |
heading | string | Product/app name displayed as the primary heading text. |
headingHref | string | Link for the heading text (e.g. product home). When no menu is present and this is the only href, the whole heading becomes one clickable link. |
href | string | Deprecated — use headingHref instead. URL to navigate to when clicked. |
superheading | string | Text above the heading (e.g. suite name). Rendered in a smaller secondary style. |
superheadingHref | string | Link for the superheading text (e.g. suite home). When provided alongside a menu, renders as an independent inline link. |
subheading | string | Text below the heading (e.g. account context). Rendered in a smaller secondary style. |
subheadingHref | string | Link for the subheading text. When provided alongside a menu, renders as an independent inline link. |
headerEndContent | ReactNode | Content rendered at the trailing edge of the heading row (e.g. a badge or status indicator). |
menu | ReactNode | Menu content shown in a popover dropdown. When provided, a chevron indicator appears automatically. Interaction boundary is determined by the presence of hrefs: no hrefs means the whole header is the trigger; with hrefs, links are independent and the chevron area is the trigger. |
as | XDSLinkComponentType | Custom component to render instead of <a>. Overrides the provider-level default set by XDSLinkProvider. Must accept href, className, style, and children props. |
xstyle | StyleXStyles | StyleX styles for layout customization. Must be a stylex.create() value. |
| Prop | Type | Description |
|---|---|---|
labelrequired | string | Accessible label for the nav item. Rendered as visible text by default. When isIconOnly is true, used as aria-label instead. |
href | string | Navigation target URL. |
isSelected | boolean (default: false) | Whether this nav item is currently selected. Sets aria-current="page" and applies highlighted styles. |
isDisabled | boolean (default: false) | Whether the nav item is disabled. Sets aria-disabled and prevents interaction. |
isIconOnly | boolean (default: false) | Renders the item as a square icon-only element. When true, label becomes the aria-label and visible text is hidden. Requires icon to be set. |
icon | ReactNode | Optional icon to display before the label. |
children | ReactNode | Custom content to render instead of the label text. |
as | XDSLinkComponentType | Custom component to render instead of <a>. Overrides the provider-level default set by XDSLinkProvider. Must accept href, className, style, and children props. |
| Prop | Type | Description |
|---|---|---|
labelrequired | string | Visible label for the trigger button. |
items | ReactNode | Menu items slot — typically XDSTopNavMegaMenuItem components, but accepts any ReactNode. |
featured | ReactNode | Featured content slot — rendered in the right panel on desktop, below items in the mobile drawer. |
delay | number (default: 150) | Delay in milliseconds before showing the menu on hover. |
hideDelay | number (default: 250) | Delay in milliseconds before hiding the menu after the mouse leaves. |
onOpenChange | (isOpen: boolean) => void | Callback fired when the mega menu opens or closes. Useful for coordinating wrapper styles. |
| Prop | Type | Description |
|---|---|---|
titlerequired | string | Card title. |
description | string | Description text below the title. |
image | string | Optional image URL displayed above the body. |
imageAlt | string | Alt text for the image. |
linkLabel | string | CTA link text. |
linkHref | string | CTA link URL. |
children | ReactNode | Custom content rendered below the standard body. |
| Prop | Type | Description |
|---|---|---|
titlerequired | string | Display title for the menu item. |
description | string | Optional description text displayed below the title. |
icon | ReactNode | Optional icon element displayed to the left. |
href | string | URL to navigate to when clicked. |
onClick | () => void | Callback when item is clicked. |
as | XDSLinkComponentType | Custom component to render instead of <a> for link items. Overrides the provider-level default set by XDSLinkProvider. |
| Prop | Type | Description |
|---|---|---|
labelrequired | string | Visible label for the trigger button. |
itemsrequired | XDSTopNavMenuItemData[] | Menu items to display in the hover popover. |
delay | number (default: 150) | Delay in milliseconds before showing the menu on hover. |
hideDelay | number (default: 200) | Delay in milliseconds before hiding the menu after the mouse leaves. |