XDS — Design System

XDSTopNavItem@xds/core · TopNav

Usage

TopNav is a horizontal navigation bar for product-level navigation in application headers. Use TopNav for 5 or fewer always-visible navigation items, or minimal navigation paired with search and controls. For complex navigation hierarchies, use a sidebar; to filter content, use tabs or filter buttons instead.

Best practices

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.

Anatomy

Element		Description
Product icon and name	required	Identifies the product in the navigation bar.
Navigation items	required	Primary links for product-level destinations.
More menu		Overflow menu for additional navigation items.
Flex area		Flexible region for search, primary action buttons, or other controls.

Import

ts
import {XDSTopNavItem} from '@xds/core/TopNav'

Props

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.

Showcase source

tsx
'use client';
import {XDSTopNav, XDSTopNavHeading, XDSTopNavItem} from '@xds/core/TopNav';
function HomeIcon() {
  return (
    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5">
      <path strokeLinecap="round" strokeLinejoin="round" d="m2.25 12 8.954-8.955c.44-.439 1.152-.439 1.591 0L21.75 12M4.5 9.75v10.125c0 .621.504 1.125 1.125 1.125H9.75v-4.875c0-.621.504-1.125 1.125-1.125h2.25c.621 0 1.125.504 1.125 1.125V21h4.125c.621 0 1.125-.504 1.125-1.125V9.75M8.25 21h8.25" />
    </svg>
  );
}
export default function TopNavItemShowcase() {
  return (
    <XDSTopNav
      label="Navigation items demo"
      heading={<XDSTopNavHeading heading="App" />}
      startContent={
        <>
          <XDSTopNavItem label="Dashboard" href="#" isSelected icon={<HomeIcon />} />
          <XDSTopNavItem label="Projects" href="#" />
          <XDSTopNavItem label="Reports" href="#" />
          <XDSTopNavItem label="Archived" href="#" isDisabled />
        </>
      }
    />
  );
}