# TopNav

- Page: https://jiguang132.com/resources/astryx/docs/top-nav
- Resource: Astryx (https://jiguang132.com/resources/astryx.md)
- All guides: https://jiguang132.com/resources/astryx/docs.md

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

```bash
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](/resources/astryx/docs/getting-started).

## 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

```json
{
  "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:

```bash
npm install @heroicons/react@2.2.0
```

---

Index of all JGuang resources: https://jiguang132.com/llms.txt