TopNav
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.
Installation
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
Requires React 19+, base CSS and a Theme provider. See Setup.
Top Nav
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.
| Prop | Type | Default | 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. | |
| children | ReactNode | Alias for startContent. Prefer startContent when composing with heading, centerContent, or endContent; children keeps the common React nav-item pattern from silently dropping items. | |
| 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 | 'Top navigation' | 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={{}}. |
Usage guidance
- Include a product logo and name in the heading slot to clearly identify the application.
- Limit primary navigation items to 5 or fewer for quick scanning and minimal cognitive load.
- Avoid: Avoid using TopNav to filter page content; use Tabs or filter controls instead.
- Avoid: Avoid deeply nested navigation hierarchies; keep menus to one level of depth.
Theming API
{
"targets": [
{
"className": "astryx-top-nav",
"states": [
"mode"
]
},
{
"className": "astryx-top-nav-item",
"states": [
"mode",
"selected"
]
},
{
"className": "astryx-top-nav-heading"
},
{
"className": "astryx-top-nav-mega-menu",
"states": [
"mode"
]
},
{
"className": "astryx-top-nav-mega-menu-item",
"states": [
"mode"
]
},
{
"className": "astryx-top-nav-mega-menu-featured-card"
},
{
"className": "astryx-top-nav-menu"
}
]
}
TopNavHeading
TopNavItem
TopNavMenu
TopNavMegaMenu
TopNavMegaMenuItem
TopNavMegaMenuFeaturedCard
Anatomy
- Product icon and name: Identifies the product in the navigation bar.
- Navigation items: 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.
Top Nav Heading
Product/suite/account heading for the TopNav heading slot. Supports smart interaction boundary logic: logo, heading text, superheading/subheading with independent links, and an optional menu popover with automatic chevron indicator.
| Prop | Type | Default | Description |
|---|---|---|---|
| logo | ReactNode | Logo element to display before the heading text. Can be an image, NavIcon, 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. | |
| 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 | LinkComponentType | Custom component to render instead of <a>. Overrides the provider-level default set by LinkProvider. Must accept href, className, style, and children props. | |
| xstyle | StyleXStyles | StyleX styles for layout customization. Must be a stylex.create() value. |
Top Nav Item
Navigation link item for use in TopNav startContent: renders as an anchor with hover and selected states.
| Prop | Type | Default | Description |
|---|---|---|---|
| label * | 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 | false | Whether this nav item is currently selected. Sets aria-current="page" and applies highlighted styles. |
| isDisabled | boolean | false | Whether the nav item is disabled. Sets aria-disabled, drops href/target so the item cannot navigate, and prevents interaction. |
| isIconOnly | boolean | 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 | LinkComponentType | Custom component to render instead of <a>. Overrides the provider-level default set by LinkProvider. Must accept href, className, style, and children props. |
Top Nav Mega Menu
Navigation item that displays a full-width mega menu panel on hover. Uses a slots API with items and featured props. TopNavMegaMenuItem renders itself in both desktop and mobile drawer modes. Supports inline collapsible drawer via render mode context.
| Prop | Type | Default | Description |
|---|---|---|---|
| label * | string | Visible label for the trigger button. | |
| items | ReactNode | Menu items slot: typically TopNavMegaMenuItem 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 | 150 | Delay in milliseconds before showing the menu on hover. |
| hideDelay | number | 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. |
Top Nav Mega Menu Featured Card
Standard featured card for the TopNavMegaMenu featured slot. Provides a consistent card with optional image, title, description, and CTA link.
| Prop | Type | Default | Description |
|---|---|---|---|
| title * | 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. When omitted, the image is explicitly decorative (alt="", role="presentation", aria-hidden), usually correct since the card already has a visible title. Provide it only when the image conveys information beyond the title and description. | |
| linkLabel | string | CTA link text. | |
| linkHref | string | CTA link URL. | |
| children | ReactNode | Custom content rendered below the standard body. |
Top Nav Mega Menu Item
An individual item inside an TopNavMegaMenu. Renders itself in both desktop (popover grid) and mobile drawer modes via render mode context.
| Prop | Type | Default | Description |
|---|---|---|---|
| title * | 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 | LinkComponentType | Custom component to render instead of <a> for link items. Overrides the provider-level default set by LinkProvider. |
Top Nav Menu
Navigation item that displays a hover-triggered popover menu with rich items containing an icon, title, and optional description.
| Prop | Type | Default | Description |
|---|---|---|---|
| label * | string | Visible label for the trigger button. | |
| items * | TopNavMenuItemData[] | Menu items to display in the hover popover. Item href values follow the shared navigation rule described on Link; rejected destinations remain visible without navigation. | |
| delay | number | 150 | Delay in milliseconds before showing the menu on hover. |
| hideDelay | number | 200 | Delay in milliseconds before hiding the menu after the mouse leaves. |
Examples
- Top Nav Heading: Demonstrates TopNavHeading with a logo and text, both as a plain display and as a clickable link.
- Top Nav Item: Demonstrates TopNavItem with selected, icon, disabled, and default states.
- Top Nav Mega Menu Featured Card: Demonstrates TopNavMegaMenuFeaturedCard with a title, description, and CTA link inside a mega menu.
- Top Nav Mega Menu Item: Demonstrates TopNavMegaMenuItem with icons, titles, and descriptions inside a mega menu.
- Top Nav Mega Menu: Demonstrates TopNavMegaMenu with items and a featured card in the mega menu panel.
- Top Nav Menu: Demonstrates TopNavMenu with a hover-triggered dropdown containing items with icons and descriptions.
- Top Nav:
- TopNav — Centered Navigation: Navigation layout with center-aligned nav items flanked by a logo heading and end actions.
- TopNav — Enterprise Dashboard: Full-featured navigation bar with icon-labeled nav items, search, notifications, and a primary CTA.
- TopNavHeading — Basic: A product heading with a logo inside a TopNav, linked to the home page. Use as the leading brand element of a top navigation bar.
- TopNav — Hover Menu: Navigation bar with a hover-triggered dropdown menu showing product items with icons and descriptions.
- TopNavItem — Basic: Navigation links inside a TopNav with one item marked as selected. Use for top-level pages of an application.
- TopNav — Mega Menu: Marketing-style navigation with a full-width mega menu featuring product items and a promotional featured card.
- TopNavMegaMenu — Basic: A mega menu trigger inside a TopNav that opens a panel of rich link items. Use when a navigation section has multiple destinations worth describing.
- TopNavMegaMenuFeaturedCard — Basic: A promotional card with a title, description, and call-to-action link. Pass it to the featured slot of a TopNavMegaMenu to highlight announcements.
- TopNavMegaMenuItem — Basic: Rich link items with an icon, title, and description. Use inside the items slot of a TopNavMegaMenu to describe each destination.
- TopNavMenu — Basic: A dropdown menu inside a TopNav built from an items array with icons and descriptions. Use to group related destinations under a single trigger.
- TopNav — Multiple Dropdowns: Navigation bar with multiple hover-triggered dropdown menus that auto-close when switching between them.
- TopNav — With Logo: Navigation bar with a branded logo icon, heading link, nav items, and a profile action.
Complete example dependencies
Some examples import optional icons. The per-example install command in the examples list identifies exactly what that example needs. For all examples on this page:
npm install @heroicons/react@2.2.0