# Navigation

Move between product areas, page views, and nested pages in one shared frame.

## Overview

Navigation shows the current location, the possible destinations, and the way back. Tempo products share one navigation model with four levels. Each level has its own component, so a control always leads to another area, another view, or one level up.

* **Product Area (SidebarMenu):** [AppShell](/docs/components/app-shell) with [SidebarMenu](/docs/components/sidebar-menu) lists the main areas and marks the current one.
* **Page (AppShell.Title):** The page title names the current page and serves as its main heading.
* **Depth (Breadcrumbs):** [Breadcrumbs](/docs/components/breadcrumbs) show the position of a nested page and lead back up.
* **View (Tabs):** [Tabs](/docs/components/tabs) switch between views of the same content without leaving the page.

[Pagination](/docs/components/pagination) moves through a long list, and [Stepper](/docs/components/stepper) marks the position in a fixed sequence of steps, such as account setup.

## Structure

A page renders the sidebar, then breadcrumbs on nested pages, one page title in `AppShell.Header` with the page actions, tabs if the page has several views of one object, and the content.

```tsx
import { AppShell, Breadcrumbs, Field, ListGroup, SidebarMenu, style, Surface, Switch, Tabs } from '@tempoxyz/ds'
import { Grid, Key, Link, Settings, Users } from '@tempoxyz/ds/icons'

export const fill = true
const pages = [
  ['Home', Grid],
  ['API Keys', Key],
  ['Webhooks', Link],
  ['Team', Users],
  ['Settings', Settings],
] as const

export function Demo() {
  return (
    <div {...styles.frame()}>
      <AppShell.Root style={{ height: '100%', minHeight: 0, overflowY: 'auto' }}>
        <AppShell.Sidebar aria-label="Console" style={{ height: '100%' }}>
          <AppShell.SidebarHeader>
            <span {...styles.product()}>Tempo Console</span>
          </AppShell.SidebarHeader>
          <AppShell.SidebarBody>
            <SidebarMenu.Root>
              {pages.map(([label, Icon]) => (
                <SidebarMenu.Item active={label === 'API Keys'} href="#" key={label}>
                  <Icon />
                  {label}
                </SidebarMenu.Item>
              ))}
            </SidebarMenu.Root>
          </AppShell.SidebarBody>
        </AppShell.Sidebar>
        <AppShell.Main>
          <Breadcrumbs>
            <Breadcrumbs.Item href="#">API Keys</Breadcrumbs.Item>
            <Breadcrumbs.Item current>Production</Breadcrumbs.Item>
          </Breadcrumbs>
          <AppShell.Header>
            <AppShell.Title>Production</AppShell.Title>
            <AppShell.Trigger />
          </AppShell.Header>
          <Tabs.Root defaultValue="overview">
            <Tabs.List aria-label="Key details">
              <Tabs.Tab value="overview">Overview</Tabs.Tab>
              <Tabs.Tab value="usage">Usage</Tabs.Tab>
              <Tabs.Tab value="settings">Settings</Tabs.Tab>
              <Tabs.Indicator />
            </Tabs.List>
            <Tabs.Panel value="overview" {...styles.panel()}>
              <Surface size="medium">
                <ListGroup.Root>
                  <ListGroup.Row>
                    <ListGroup.Label>Created</ListGroup.Label>
                    March 3, 2026
                  </ListGroup.Row>
                  <ListGroup.Row>
                    <ListGroup.Label>Last used</ListGroup.Label>2 minutes ago
                  </ListGroup.Row>
                  <ListGroup.Row>
                    <ListGroup.Label>Network</ListGroup.Label>
                    Mainnet
                  </ListGroup.Row>
                </ListGroup.Root>
              </Surface>
            </Tabs.Panel>
            <Tabs.Panel value="usage" {...styles.panel()}>
              <Surface size="medium">
                <ListGroup.Root>
                  <ListGroup.Row>
                    <ListGroup.Label>Requests, last 24 hours</ListGroup.Label>
                    12,480
                  </ListGroup.Row>
                  <ListGroup.Row>
                    <ListGroup.Label>Errors</ListGroup.Label>3
                  </ListGroup.Row>
                </ListGroup.Root>
              </Surface>
            </Tabs.Panel>
            <Tabs.Panel value="settings" {...styles.panel()}>
              <Surface size="medium">
                <Field.Root>
                  <Field.Label>Allow testnet requests</Field.Label>
                  <Switch />
                  <Field.Description>
                    Use this key against testnet as well as mainnet.
                  </Field.Description>
                </Field.Root>
              </Surface>
            </Tabs.Panel>
          </Tabs.Root>
        </AppShell.Main>
      </AppShell.Root>
    </div>
  )
}

namespace styles {
  // The transform makes the frame the containing block for the drawer below 1024px.
  export const frame = style({
    borderRadius: 'sm',
    height: '32rem !custom',
    overflow: 'hidden',
    transform: 'translateZ(0) !custom',
    selectors: {
      ':root[data-maximized] &': { borderRadius: '0px !custom', height: '100vh !custom' },
    },
  })

  export const panel = style({ marginBlockStart: '16' })

  export const product = style({ paddingInline: '12', typography: 'body.b2Strong' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/ConsoleNavigation.tsx)

This reference layout uses [AppShell](/docs/components/app-shell), [SidebarMenu](/docs/components/sidebar-menu), [Breadcrumbs](/docs/components/breadcrumbs), and [Tabs](/docs/components/tabs). On a wide display, open the preview full screen for the sticky sidebar.

## Product Navigation

Put every product area in the [SidebarMenu](/docs/components/sidebar-menu) inside `AppShell.Sidebar`, in the same order on every page.

* **One Active Item (active):** Mark only the area of the current page. It sets `aria-current="page"`.
* **Consistent Icons:** Items do not wrap. Give each one a short label and an icon, never a mix with and without.
* **Grouped Sections (SidebarMenu.Group):** Past about seven items, group them under specific labels, such as Project and Organization.

**Do:** Mark the current area `active`, with short labels and icons.

```tsx
/**
 * Do example for "Navigation" on the Navigation page.
 * Mark the current area `active`, with short labels and icons.
 * @module
 */
import { SidebarMenu, style } from '@tempoxyz/ds'
import { Grid, Key, Link, Users } from '@tempoxyz/ds/icons'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <SidebarMenu.Root aria-label="Console" {...styles.column()}>
      <SidebarMenu.Item href="#">
        <Grid />
        Home
      </SidebarMenu.Item>
      <SidebarMenu.Item active href="#">
        <Key />
        API Keys
      </SidebarMenu.Item>
      <SidebarMenu.Item href="#">
        <Link />
        Webhooks
      </SidebarMenu.Item>
      <SidebarMenu.Item href="#">
        <Users />
        Team
      </SidebarMenu.Item>
    </SidebarMenu.Root>
  )
}

namespace styles {
  export const column = style({ width: '15rem !custom' })
}
```

**Don't:** Leave the current area unmarked.

```tsx
/** Don't example for "Navigation" on the Navigation page. Don't leave the current area unmarked. @module */
import { SidebarMenu, style } from '@tempoxyz/ds'
import { Grid, Key, Link, Users } from '@tempoxyz/ds/icons'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <SidebarMenu.Root aria-label="Console" {...styles.column()}>
      <SidebarMenu.Item href="#">
        <Grid />
        Home
      </SidebarMenu.Item>
      <SidebarMenu.Item href="#">
        <Key />
        API Keys
      </SidebarMenu.Item>
      <SidebarMenu.Item href="#">
        <Link />
        Webhooks
      </SidebarMenu.Item>
      <SidebarMenu.Item href="#">
        <Users />
        Team
      </SidebarMenu.Item>
    </SidebarMenu.Root>
  )
}

namespace styles {
  export const column = style({ width: '15rem !custom' })
}
```

### Move the Sidebar Into a Drawer Below 1024px

Below 1024px, `AppShell.Sidebar` renders as a modal drawer from the right edge, with the same items in the same order. `AppShell.Trigger` toggles it from a menu button at the end of the bottom bar, which hides from 1024px.

* **Main Action in the Header (AppShell.Header):** Keep the main action in the header, not the drawer.
* **Server Rendering (Hydration):** The server emits the wide layout. Narrow screens switch to the drawer after hydration.

## Tabs

Use [Tabs](/docs/components/tabs) when a page shows several views of one object, such as the Overview, Usage, and Settings of an API key.

* **Another page:** Use [SidebarMenu](/docs/components/sidebar-menu) or links.
* **A mode of the same content:** Use [ChoiceGroup](/docs/components/choice-group), such as for the time range of a chart.
* **Tabs inside tabs:** Never nest them. Split the view, or move the inner level to its own page.

If tabs overflow one line, the list scrolls horizontally. Set `expand` on `Tabs.List` to stretch tabs across a narrow column.

**Do:** Use one or two words per tab, in parallel form.

```tsx
/**
 * Do example for "Move the Sidebar Into a Drawer Below 1024px" on the Navigation page.
 * Use one or two words per tab, in parallel form.
 * @module
 */
import { Tabs } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Tabs.Root defaultValue="overview">
      <Tabs.List aria-label="Key details">
        <Tabs.Tab value="overview">Overview</Tabs.Tab>
        <Tabs.Tab value="usage">Usage</Tabs.Tab>
        <Tabs.Tab value="settings">Settings</Tabs.Tab>
        <Tabs.Indicator />
      </Tabs.List>
    </Tabs.Root>
  )
}
```

**Don't:** Write long or mismatched tab labels.

```tsx
/**
 * Don't example for "Move the Sidebar Into a Drawer Below 1024px" on the Navigation page.
 * Don't write long or mismatched tab labels.
 * @module
 */
import { Tabs } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Tabs.Root defaultValue="overview">
      <Tabs.List aria-label="Key details">
        <Tabs.Tab value="overview">About this key</Tabs.Tab>
        <Tabs.Tab value="usage">Requests in the last 30 days</Tabs.Tab>
        <Tabs.Tab value="settings">Configure</Tabs.Tab>
        <Tabs.Indicator />
      </Tabs.List>
    </Tabs.Root>
  )
}
```

## Breadcrumbs

Use [Breadcrumbs](/docs/components/breadcrumbs) on pages below a product area, such as a key under API Keys or an invoice inside Payments. Start with the product area, follow the hierarchy rather than the visit history, and mark the last item `current`.

**Do:** Show the path from the product area down to the current page.

```tsx
/**
 * Do example for "Move the Sidebar Into a Drawer Below 1024px" on the Navigation page.
 * Show the path from the product area down to the current page.
 * @module
 */
import { Breadcrumbs } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Breadcrumbs>
      <Breadcrumbs.Item href="#">Settings</Breadcrumbs.Item>
      <Breadcrumbs.Item href="#">Webhooks</Breadcrumbs.Item>
      <Breadcrumbs.Item current>Order events</Breadcrumbs.Item>
    </Breadcrumbs>
  )
}
```

**Don't:** Show breadcrumbs on a top-level page, where they hold only the current page.

```tsx
/**
 * Don't example for "Move the Sidebar Into a Drawer Below 1024px" on the Navigation page.
 * Don't show breadcrumbs on a top-level page, where they hold only the current page.
 * @module
 */
import { Breadcrumbs } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Breadcrumbs>
      <Breadcrumbs.Item current>API Keys</Breadcrumbs.Item>
    </Breadcrumbs>
  )
}
```

If the full path would wrap on a narrow screen, show only the parent page as a back link, such as a secondary `Button.Link` from [Button](/docs/components/button) with an arrow icon and the parent's name.

## Pagination

Use [Pagination](/docs/components/pagination) for long lists that load page by page and need a stable position, such as transaction history. [Tables and Lists](/docs/patterns/tables-and-lists#paginate-or-load-more) covers when to page and when to load more.

## Best Practices

* **Location in the URL:** Reflect the selected tab and page in the URL, so links and the back button work.
* **Links for Navigation (Button.Link):** Use a link to change pages. Put commands, such as Log out, in a [Menu](/docs/components/menu) in the sidebar footer.

## States

* **Loading and Error:** Navigation renders at once and works. Only the main column shows placeholders and errors.
* **Empty:** A product area with no content still appears in the sidebar. Its page shows an [empty state](/docs/patterns/empty-states).
* **Disabled:** Leave out unavailable areas. Disable a tab only if its view does not apply yet, and state the reason.
* **Success:** After a flow such as key creation, open the page of the new item with its area marked active.

## Content

Name destinations with nouns, such as Activity, not verbs, such as View activity. Use the same name in the sidebar, the page title, and the breadcrumb. [Writing Style](/docs/foundations/content/writing-style) covers capitalization.

## Accessibility

* **Landmarks (aria-label):** Sidebar, breadcrumbs, and pagination are named landmarks. Rename one if two share a kind.
* **Sidebar Drawer (Escape):** The drawer takes focus, also closes on the backdrop or a swipe, and returns focus to the menu button.
* **One Page Title (h1):** The page title is the page's heading. Render exactly one title per page.
* **Named Tab Lists (aria-label):** Give every tab list a name that states its content, such as Key details.
* **Skip Links (AppShell.Main):** If the sidebar holds many links, add a skip link to the main column.

## Related

[AppShell](/docs/components/app-shell)

Use for the application frame.

[SidebarMenu](/docs/components/sidebar-menu)

Use for links to product areas.

[Tabs](/docs/components/tabs)

Use for views of a page.

[Breadcrumbs](/docs/components/breadcrumbs)

Use for nested pages.

[Pagination](/docs/components/pagination)

Use for long lists.

[Stepper](/docs/components/stepper)

Use for fixed sequences of steps.

[Responsive Layout](/docs/patterns/responsive-layout)

Covers breakpoints.

[Tempo Console](/docs/products/tempo-console)

Covers the console's pages.
