# Top navigation
The header bar of a site or app, with regions for identity, navigation, and actions. Arrange the regions with your own CSS; this page has recipes to start from.
```tsx
// demo.tsx
import {SearchIcon} from '@earendil-works/elanor-icons-react';
import {Link, TopNavigation} from '@earendil-works/elanor-react';
import styles from './top-navigation.module.css';
export default function TopNavigationDemo() {
return (
Acme
Sign in
);
}
```
```css
/* top-navigation.module.css */
.links {
display: flex;
flex-wrap: wrap;
gap: var(--semantic-dimension-space-gap-medium);
}
```
## Usage
```tsx
import {TopNavigation} from '@earendil-works/elanor-react';
;
```
Root renders a `header`; the regions render `div`s. Put links inside a `nav` with an `aria-label`, or use [Navigation menu](/components/navigation-menu.md) for submenus.
`Link` renders an `a` in `semantic.color.text.secondary`, `semantic.color.text.primary` on hover; `active` marks the current page or section with `aria-current="page"` in primary text. It passes its props and ref through, so a router can wrap it. `ActionButton` is an icon button for the bar's actions, such as search or a theme switch, styled like the menu's trigger: `semantic.dimension.size.large` square, its icon `semantic.dimension.size.icon`. It renders a `button`; name it with `aria-label`. In a [Layout](/components/layout.md), merge Root into the header with `}>`.
By default, the regions share one row, with free space between them, and wrap when space runs out. The navigation sits centered only when identity and actions have the same width; in the demo above, it is pushed left.
## Height
Root is `semantic.dimension.size.topNavigation` (64px) tall and centers its content, so the bar needs no block padding. With `box-sizing: border-box`, a bottom border you add counts toward the 64px. The height is fixed so that offsets below the bar can come from the same token: a sticky header and the page's scroll padding, so anchor jumps and focused elements stay clear of it. The token is in rem, so the bar grows with the user's font size.
Keep the bar to one row: on narrow screens, move links into a [Drawer](/components/drawer.md) or a menu, as in [Responsive navigation](#responsive-navigation). Layouts that need more rows, like the stacked and centered recipes below, set `block-size: auto`; derive offsets for such headers from their measured height instead of the token.
```css
.header {
position: sticky;
inset-block-start: 0;
z-index: var(--semantic-number-layer-sticky);
border-block-end: var(--semantic-dimension-border-width-small) solid
var(--semantic-color-border-secondary);
background: var(--semantic-color-background-canvas);
}
html {
scroll-padding-block-start: var(--semantic-dimension-size-top-navigation);
}
```
## Centered
Equal side columns keep the navigation centered, whatever the widths of identity and actions. Compare it with the demo at the top of the page. In narrow containers, the links move to their own row.
```tsx
// centered.tsx
import {Link, TopNavigation} from '@earendil-works/elanor-react';
import styles from './centered.module.css';
export default function TopNavigationCentered() {
return (
Acme
Contact sales
Sign in
);
}
```
```css
/* centered.module.css */
.frame {
container: navigation / inline-size;
}
.header {
display: grid;
grid-template-columns: repeat(2, minmax(0, 1fr));
/* Two rows in narrow containers: opt out of the bar's fixed height. */
block-size: auto;
padding-block: var(--semantic-dimension-space-padding-xx-large);
}
.navigation {
grid-column: 1 / -1;
grid-row: 2;
justify-content: center;
}
.links {
display: flex;
flex-wrap: wrap;
gap: var(--semantic-dimension-space-gap-medium);
}
.actions {
grid-column: 2;
grid-row: 1;
justify-self: end;
}
/* Container queries can't use var(), so the threshold is the token's resolved value. */
@container navigation (width >= 40rem /* token: semantic.dimension.breakpoint.xSmall */) {
.header {
grid-template-columns: minmax(0, 1fr) auto minmax(0, 1fr);
block-size: var(--semantic-dimension-size-top-navigation);
padding-block: 0;
}
.navigation {
grid-column: 2;
grid-row: 1;
}
.actions {
grid-column: 3;
}
}
```
## Stacked
Identity and actions on one row, navigation on the row below.
```tsx
// stacked.tsx
import {Link, TopNavigation} from '@earendil-works/elanor-react';
import styles from './stacked.module.css';
export default function TopNavigationStacked() {
return (
Acme
Sign in
);
}
```
```css
/* stacked.module.css */
.header {
display: grid;
grid-template-columns: repeat(2, minmax(0, 1fr));
/* Two rows: opt out of the bar's fixed height. */
block-size: auto;
padding-block: var(--semantic-dimension-space-padding-xx-large);
}
.actions {
justify-self: end;
}
.navigation {
grid-column: 1 / -1;
}
.links {
display: flex;
flex-wrap: wrap;
gap: var(--semantic-dimension-space-gap-medium);
}
```
## Menu
For narrow screens, `Menu` collapses the navigation into a menu below the bar. `MenuTrigger` shows the menu icon, and the close icon while the menu is open; `MenuPopup` fills the window below `semantic.dimension.size.topNavigation`. It is built on Base UI's Dialog without modality: Escape, the trigger, and choosing a link close it, and the bar's other controls, such as a theme switcher, stay usable and leave it open. Put the panels in a `nav` named like the navigation it replaces.
```tsx
// menu.tsx
import {Link, Text, TopNavigation} from '@earendil-works/elanor-react';
import {useRef} from 'react';
import styles from './menu.module.css';
const start = ['Introduction', 'Installation'];
const guides = ['Deploying a project', 'Rollbacks'];
const reference = ['Command-line tool', 'Configuration file'];
export default function TopNavigationMenuDemo() {
const frameRef = useRef(null);
return (
Acme
Open the menu, then open Docs.
);
}
```
```css
/* menu.module.css */
.frame {
/* Demo only: the fixed menu is placed within the frame. Layout containment only: with paint
containment, WebKit misses clicks on the menu's panels. */
contain: layout;
/* stylelint-disable-next-line design-tokens/no-hardcoded-token-values -- Demo frame size. */
block-size: 28rem;
border: var(--semantic-dimension-border-width-default) solid
var(--semantic-color-border-secondary);
}
.header {
padding-inline: var(--semantic-dimension-space-padding-x-large);
border-block-end: var(--semantic-dimension-border-width-small) solid
var(--semantic-color-border-secondary);
}
.content {
padding: var(--semantic-dimension-space-padding-x-large);
}
```
```tsx
```
Panels hold the menu's levels. Each opening starts at `defaultPanel`; a `MenuPanelTrigger` slides to a nested panel, which starts with a back button and takes focus there. Panels slide with `semantic.transition.movement.disclosure`, instantly when the reader prefers reduced motion. One level of nesting. Within a panel, `MenuCollapsible` sections open in place, like [Side navigation](/components/side-navigation.md)'s, and `MenuGroup` gathers lists under a `MenuGroupLabel`, which names the group for assistive technology. Groups are optional, but every group needs a label.
Items are styled for the menu on their own, not shared with Side navigation. `active` marks the current page with `aria-current="page"`, or the panel trigger that contains it with `aria-current="true"`; a section that contains the current page is marked too. Render the menu and the wide navigation from the same data, and switch between them with your CSS at your breakpoint.
`MenuLink` renders an `a` and passes its props and ref through, so a router can wrap it. A router link that sets `aria-current="page"` on the active link, like TanStack Router's, marks the current page without `active`:
```tsx
const MenuLink = createLink(TopNavigation.MenuLink);
Rollbacks;
```
### Static rendering
On pages rendered on the server without React in the browser, use the static menu parts; `MenuList` and `MenuItem` stay the same:
```tsx
```
```ts
import {createCollapsible, createTopNavigationMenu, enhance} from '@earendil-works/elanor-react';
enhance({'top-navigation-menu': createTopNavigationMenu, collapsible: createCollapsible});
```
The popup is a native popover. The behavior opens and closes it like the React menu: Escape and choosing a link close it, presses outside leave it open, panels slide with the same focus moves, and each opening starts at `defaultPanel`. Without the behavior, the trigger still opens and closes it.
## Responsive navigation
On desktop, destinations are in a [Sidebar](/components/sidebar.md) and resources in the header. Below `semantic.dimension.breakpoint.medium`, both move into a [Drawer](/components/drawer.md). They share the current selection; the sidebar's collapsed state stays separate from the drawer's open state.
The drawer closes when the window grows past the breakpoint, rather than being hidden by CSS. Try it: open the drawer on a narrow window, then widen it. The demo keeps selection in local state and opens the drawer inside its frame with Portal's `container`; an application uses its router and lets the drawer cover the viewport.
```tsx
// responsive.tsx
import {CloseIcon, MenuIcon} from '@earendil-works/elanor-icons-react';
import {
Drawer,
Heading,
IconButton,
Layout,
Link,
SideNavigation,
Sidebar,
Stack,
Text,
TopNavigation,
type DrawerRootActions,
} from '@earendil-works/elanor-react';
import {useEffect, useRef, useState} from 'react';
import styles from './responsive.module.css';
const pages = ['Overview', 'Projects', 'Activity', 'Members', 'Usage', 'Billing', 'Settings'];
function Destinations({
active,
collapsed = false,
onSelect,
}: {
readonly active: string;
readonly collapsed?: boolean;
readonly onSelect: (page: string) => void;
}) {
return (
{pages.map((page) => (
{
// This demo selects local content; real applications supply their router links.
event.preventDefault();
onSelect(page);
}}
>
{page}
))}
);
}
function Resources({onNavigate}: {readonly onNavigate?: () => void}) {
return (
);
}
export default function TopNavigationResponsive() {
const [active, setActive] = useState('Overview');
const [collapsed, setCollapsed] = useState(false);
const actionsRef = useRef(null);
const triggerRef = useRef(null);
const contentRef = useRef(null);
// Only for this demo: the drawer opens inside the application frame, not over the docs page.
const applicationRef = useRef(null);
useEffect(() => {
// CSS owns presentation. Only release the modal when its trigger becomes unavailable.
const breakpoint = getComputedStyle(document.documentElement)
.getPropertyValue('--semantic-dimension-breakpoint-medium')
.trim();
const desktop = window.matchMedia(`(min-width: ${breakpoint})`);
const close = () => actionsRef.current?.close();
const onBreakpointChange = () => {
if (desktop.matches) close();
};
desktop.addEventListener('change', onBreakpointChange);
return () => desktop.removeEventListener('change', onBreakpointChange);
}, []);
return (
}
className={styles.application}
>
} className={styles.header}>
Acme workspace
}
>
}
className={`${styles.desktopOnly} ${styles.sidebar}`}
>
} ref={contentRef} tabIndex={-1} className={styles.content}>
{active}Select a destination, or resize the window with the drawer open.
triggerRef.current?.getClientRects().length ? triggerRef.current : contentRef.current
}
>
Workspace navigation}>
{
setActive(page);
actionsRef.current?.close();
}}
/>
actionsRef.current?.close()} />
);
}
```
```css
/* responsive.module.css */
.application {
/* Demo only: fixed-position drawer parts are placed and clipped within the frame. */
contain: layout paint;
display: grid;
grid-template-rows: auto minmax(0, 1fr);
/* stylelint-disable-next-line design-tokens/no-hardcoded-token-values -- Demo frame size. */
block-size: 30rem;
min-block-size: 0;
border: var(--semantic-dimension-border-width-default) solid
var(--semantic-color-border-secondary);
}
.header {
padding: var(--semantic-dimension-space-padding-large);
border-block-end: var(--semantic-dimension-border-width-default) solid
var(--semantic-color-border-secondary);
}
.links {
display: flex;
flex-wrap: wrap;
gap: var(--semantic-dimension-space-gap-medium);
}
.body {
min-block-size: 0;
}
.content {
overflow: auto;
padding: var(--semantic-dimension-space-padding-x-large);
}
/* Anchor the Drawer to the viewport above the application. */
.overlay {
position: fixed;
inset: 0;
z-index: var(--semantic-number-layer-overlay);
}
.desktopOnly {
display: none;
}
/* Media queries can't use var(), so the threshold is the token's resolved value. */
@media (width >= 64rem /* token: semantic.dimension.breakpoint.medium */) {
.desktopOnly {
display: flex;
}
.sidebar {
position: static;
block-size: 100%;
max-block-size: 100%;
}
.mobileOnly {
display: none;
}
}
```
## API
### `TopNavigation.Root`
Renders ``. Accepts its HTML attributes and `ref`.
### `TopNavigation.Identity`
Renders `
`. Accepts its HTML attributes and `ref`.
### `TopNavigation.Navigation`
Renders `
`. Accepts its HTML attributes and `ref`.
### `TopNavigation.Link`
A link in the bar's navigation.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `active` | `boolean` | `false` | Marks the current page or section with `aria-current="page"`. Router links that set `aria-current` themselves need no `active`. |
Renders ``. Also accepts its HTML attributes and `ref`.
### `TopNavigation.Actions`
Renders `