---
title: Navigation
description: Define navigation groups once and connect them to desktop and mobile surfaces.
order: 12
toc:
  - id: define-groups
    title: Define groups
  - id: provide-navigation
    title: Provide navigation
  - id: route-state
    title: Route state
---

## Define groups {#define-groups}

Start with typed `NavigationGroup` values. Items may represent direct routes or nested navigation branches.

```ts
import type { NavigationGroup } from "@workspace/blocks/navigation"

export const navigationGroups: NavigationGroup[] = [
  {
    id: "workspace",
    label: "Workspace",
    items: [
      { id: "dashboard", label: "Dashboard", to: "/dashboard" },
      { id: "media", label: "Media", to: "/media" },
    ],
  },
]
```

## Provide navigation {#provide-navigation}

`AppLayout` already mounts the provider and the responsive navigation surfaces. For a custom shell, compose them directly:

```tsx
<NavigationProvider groups={navigationGroups}>
  <PrimaryNavigation groups={navigationGroups} />
  <MobileNavigationSheet groups={navigationGroups} />
</NavigationProvider>
```

## Route state {#route-state}

Use `resolveNavigationRouteState` for the standard route model. Applications with custom routing can supply a `GetNavigationRouteState` implementation while keeping the same navigation UI.