# Navigation Configuration

> The signed-in app shell (sidebar, header, breadcrumbs, account menu) and how to edit its navigation.

*Canonical: https://makerkit.dev/docs/void-cloudflare/configuration/navigation*

---

Every page in `apps/web/pages/(app)/` renders inside the app shell: a sidebar with your navigation and the account menu, and a header with the sidebar button and breadcrumbs. Settings pages use their own sidebar (see [Settings Pages](#settings-pages)). The navigation is defined in `apps/web/config/navigation.config.tsx`. This file is yours: edit it freely.

This page is part of the [Configuration documentation](./overview).

## The Config

```tsx
// apps/web/config/navigation.config.tsx
import { Home, Settings } from 'lucide-react';
import type {
  NavigationGroup,
  NavigationItem,
} from '@kit/ui/navigation-schema';

import {
  hasSettingsPages,
  type NavigationContext,
} from '#/lib/settings-navigation.ts';

import { authPaths } from './auth-paths';

const iconClasses = 'w-4';

export function getNavigation(context: NavigationContext) {
  const application: NavigationItem[] = [
    {
      label: 'app.routes.dashboard',
      path: context.config.appHomePath,
      Icon: <Home className={iconClasses} />,
    },
  ];

  // last, and only when /settings has a page to land on
  const settings: NavigationItem = {
    label: 'app.routes.settings',
    path: authPaths.settings,
    Icon: <Settings className={iconClasses} />,
  };

  const showSettings = hasSettingsPages(context);

  return [
    {
      label: 'app.routes.application',
      children: showSettings ? [...application, settings] : application,
    },
  ] satisfies NavigationGroup[];
}
```

The defaults are Application → Dashboard (`APP_HOME_PATH`, `/dashboard`) and one Settings item, last, to `/settings`. Settings pages aren't listed here: they have their own sidebar (see [Settings Pages](#settings-pages)). The item, and the account menu's Settings, show only while `hasSettingsPages(context)` is true, the rule `/settings` uses to pick a page. With the shipped entries that's always: Profile is shown to every signed-in user. These are editable defaults; unit tests do not pin their order, labels or destinations.

Navigation renders in the browser, so it can't read env. It's a function of the shared data instead: `config` (the public config) and `organization` (the active organization with the user's roles, or null in the personal context). Call it with `getNavigation(useShared())`.

## Entries

Each group has a `label` and `children`. Optionally, `translate: false` shows the label as written instead of looking it up as a message key, truncated with the full text as its tooltip. The settings sidebar uses it for the organization's name. Each child has:

- `label`, `path`, optional `Icon` (a Lucide icon)
- `highlightMatch`: a regex string for when the item counts as active (default: the path and anything below it)
- `children`: one level of sub-items
- `collapsible`, `collapsed`, `renderAction`
- `context`: `personal`, `organization` or `all`, to show an item only in one account context

Typing the lists as `NavigationGroup[]` and `NavigationItem[]` (`@kit/ui/navigation-schema`) makes a wrong key or type fail `pnpm check` with the file and line.

## Showing Items Conditionally

Push items behind an `if`, with the public flags or the active organization:

```tsx
export function getNavigation({ config, organization }: NavigationContext) {
  const application: NavigationItem[] = [
    { label: 'app.routes.dashboard', path: config.appHomePath },
  ];

  // e.g. a page about the active organization
  if (organization) {
    application.push({ label: 'app.routes.projects', path: '/projects' });
  }

  return [{ label: 'app.routes.application', children: application }];
}
```

## Labels

A `label` is a message key, `<namespace>.<key>`. The default items use `apps/web/messages/en/app.json`:

```json
{ "routes": { "dashboard": "Dashboard", "settings": "Settings" } }
```

To add an item, add its key to that file (and to every other locale's `app.json`), then use it as the label. Render labels with `Trans`, which falls back to the label itself, so plain text also works:

```tsx
import { Trans } from '@kit/ui/trans';

<Trans i18nKey={item.label} defaults={item.label} />;
```

## The App Shell

| File | Owner | What it does |
| --- | --- | --- |
| `apps/web/config/navigation.config.tsx` | you | The sidebar's groups and items |
| `apps/web/config/settings-navigation.config.tsx` | you | Every settings page: group, label, icon, when to show it |
| `apps/web/pages/(app)/layout.tsx` | you | Composes the shell: `<AppSidebar navigation={getNavigation(useShared())}>` |
| `apps/web/pages/_layouts/settings.tsx` | you | Composes the settings shell for pages exporting `layout = 'settings'` |
| `apps/web/components/dashboard-demo.tsx`, `dashboard-demo-data.ts` | you | The demo on `/dashboard` (fake numbers): replace `<DashboardDemo />` and delete both |
| `apps/web/components/app-sidebar.tsx` | kit | Sidebar, account switcher (or logo), account menu in the footer |
| `apps/web/components/settings-sidebar.tsx` | kit | The settings sidebar: Back to app, then the settings groups |
| `apps/web/components/sidebar-shell.tsx` | kit | What both sidebars share (provider, account menu, page area) |
| `apps/web/components/settings-page-body.tsx` | kit | `SettingsPageBody`: the one column width of every settings page |
| `apps/web/lib/settings-navigation.ts` | kit | `visibleSettings`, the one rule for which settings pages show; the `/settings` target |
| `apps/web/components/app-page-header.tsx` | kit | `AppPageHeader`: sidebar button and breadcrumbs |
| `apps/web/components/account-dropdown.tsx` | kit | Name, email, Settings, theme, sign out |
| `apps/web/middleware/07.sidebar.ts` | kit | Reads the collapsed state for the first render |
| `@kit/ui/sidebar-navigation`, `@kit/ui/app-breadcrumbs` | kit | The router-free components behind them |

Kit-owned files change with kit updates: customize through your files above rather than editing them, so updates merge cleanly.

## Adding a Page

1. Create the page under `pages/(app)/`; the folder makes it signed-in only. Its loader still calls `requireSession({ c })`.
2. Render `AppPageHeader` first, then `PageBody`.
3. Add an item to `navigation.config.tsx` and its label to `messages/<locale>/app.json`. A page under `settings/` goes in the settings sidebar instead: see [Adding a Settings Page](#adding-a-settings-page).

```tsx
// apps/web/pages/(app)/projects/index.tsx
import { PageBody } from '@kit/ui/page';

import { AppPageHeader } from '#/components/app-page-header.tsx';

export default function ProjectsPage() {
  return (
    <>
      <AppPageHeader />

      <PageBody>…</PageBody>
    </>
  );
}
```

```tsx
// navigation.config.tsx: inside a group's children
{ label: 'app.routes.projects', path: '/projects', Icon: <FolderIcon className={iconClasses} /> },
```

## Settings Pages

Pages under `pages/(app)/settings/` render in a settings-only sidebar instead of the app's: **Back to app** (to the app home), **Your account**, then a group titled with the active organization's name. They stay in `(app)/`, so they're still signed-in only.

`/settings` itself redirects to the first page the user can see: the account's first (Profile, always shown), else the organization's. It answers 404 when none is visible.

### Adding a Settings Page

One page file and one config entry. An owner-only Integrations page (the kit's own `/settings/billing` is the billing page):

```tsx
// apps/web/pages/(app)/settings/integrations.tsx
import { AppPageHeader } from '#/components/app-page-header.tsx';
import { SettingsPageBody } from '#/components/settings-page-body.tsx';

// the settings shell (pages/_layouts/settings.tsx)
export const layout = 'settings';

export default function IntegrationsPage() {
  return (
    <>
      <AppPageHeader />

      <SettingsPageBody className="gap-6">…</SettingsPageBody>
    </>
  );
}
```

```ts
// apps/web/pages/(app)/settings/integrations.server.ts
import { HTTPException } from 'hono/http-exception';
import { defineHandler } from 'void';

import { DELETE_ORGANIZATION, hasPermission } from '@kit/organizations';

import { requireActiveOrganization } from '#/lib/organizations.server.ts';

export const loader = defineHandler((c) => {
  // the access check: the nav entry below only hides the link
  const organization = requireActiveOrganization({ c });

  // a permission, not a role name: custom roles keep working
  if (!hasPermission(organization, DELETE_ORGANIZATION)) {
    throw new HTTPException(404);
  }

  return {};
});
```

```tsx
// apps/web/config/settings-navigation.config.tsx: add to the list
// (import Plug from 'lucide-react')
{
  group: 'organization',
  label: 'app.routes.integrations',
  path: '/settings/integrations',
  Icon: <Plug className={iconClasses} />,
  visible: ({ organization }) => hasPermission(organization, DELETE_ORGANIZATION),
},
```

Then add `routes.integrations` to `messages/<locale>/app.json`. The crumbs read `Settings › Integrations`, and the main sidebar's Settings item and the account menu need nothing.

- `group`: `account` or `organization`. Account pages are the user's own: shown in every context, and open without an organization in organizations-only mode. Organization pages show only while one is active, and their `visible` gets that organization, never null.
- `visible`: when to show the link, from `config` and `organization`. Omitted: always. For role checks, prefer `hasPermission(organization, permission)` from `@kit/organizations` over role names. **It is navigation only.** It doesn't stop anyone opening the URL: the page's loader must check access itself (`requireSession`, `requireActiveOrganization`, a permission) and answer 404, as above.
- Order counts within a group; the kit places the groups.
- `SettingsPageBody` gives every settings page the same column, so the content doesn't shift as you move between them.
- `export const layout = 'settings'` is what puts the page in the settings shell (a Void named layout: `apps/web/node_modules/void/docs/guide/pages-routing/layouts.md`). It replaces `(app)/layout.tsx` and keeps the root layout, so put providers both shells need in the root layout.

After changing the entries, open the affected pages and check the visible links and settings shell. Service and page-action tests cover authorization; unit tests do not pin the example navigation configuration.

## Breadcrumbs

`AppPageHeader` builds the crumbs from the URL. Each part of the path gets a crumb when a navigation item has exactly that path (its label, translated) or when the page gives it a label. Group labels are never crumbs, and a part nobody labels is left out, so text from the URL is never shown.

Name the ids in your URLs with `labels`, keyed by the path segment:

```tsx
// apps/web/pages/(app)/projects/[id].tsx → Projects › Acme site
export default function ProjectPage({ project }: Props) {
  return (
    <>
      <AppPageHeader labels={{ [project.id]: project.name }} />

      <PageBody>…</PageBody>
    </>
  );
}
```

Page labels are shown as text (not translated, never HTML). The locale prefix (`/it/projects`) is ignored.

## Collapsed Sidebar and Mobile

- The header button collapses the desktop sidebar to icons; item labels become tooltips. The choice is stored in the `sidebar_state` cookie (only `false` collapses; anything else means expanded) and read by `middleware/07.sidebar.ts`, so the server renders it as the user left it.
- Below 768px the sidebar becomes a sheet opened from the same button; following a link closes it.
- Browser-only UI in your pages (charts, anything reading `window`) goes inside `BrowserOnly` (`@kit/ui/browser-only`) with a same-size fallback, so the server and the first render match.

## Active Items

The sidebar highlights the item whose path matches the current one, ignoring the locale prefix: `/projects` stays active on `/projects/42`, but not on `/projects-archive`. Use `highlightMatch` (a regex string) for anything else. For your own navigation elsewhere, use the same helper:

```tsx
import { useRouter } from '@void/react';

import { isRouteActive } from '@kit/ui/utils';

const { path } = useRouter();
const active = isRouteActive(item.path, path, item.highlightMatch);
```

## Marketing Navigation

The marketing header and footer links (`pages/(marketing)/layout.tsx`) come from `apps/web/config/marketing-navigation.config.ts`, also yours:

```ts
export const marketingNavigation = MarketingNavigationSchema.parse({
  header: [
    { label: 'marketing.nav.features', path: '/#features' },
    { label: 'marketing.nav.faq', path: '/faq' },
  ],
  footer: [
    {
      label: 'marketing.footer.product', // column heading
      links: [{ label: 'marketing.nav.faq', path: '/faq' }],
    },
    {
      label: 'marketing.footer.legal',
      links: [{ label: 'marketing.legal.privacy', path: '/privacy-policy' }],
    },
  ],
});
```

- `header` is the top nav, `footer` the footer's link columns (each with a heading `label`; legal pages sit in the Legal column).
- `label` is a message key in `apps/web/messages/<locale>/marketing.json`; the footer description and copyright are `marketing.footer.description` and `marketing.footer.copyright` (`{productName}`, `{year}`). `{year}` is the year the page was rendered: a cached page keeps it until the next deploy, and the browser doesn't update it (no hydration mismatch).
- `path` is a site path (`/faq`, `/#features`) or an `https://` URL. Anything else (`javascript:`, `data:`, `http:`, `//host`, `/../`) fails the parse when the app loads, with an error giving the entry's path (`["header", 1, "path"]`) and the bad value. A label key with no message renders as the key.
- Every link, like the header's Sign in, Get started and Dashboard buttons (Dashboard for signed-in visitors, to `APP_HOME_PATH`), reloads the document (`LocalizedLink` with `reloadDocument`, through `MarketingLink` for nav links) instead of navigating client-side. Cached marketing pages have no CSP, so the next page, often an app or auth page, needs a full load to get its own. Site paths keep the visitor's locale prefix (`/it/faq`); `https://` URLs open in a new tab with `rel="noopener noreferrer"`.
- Below the `md` breakpoint the header's links and buttons move into a menu sheet (`SiteHeader` from `@kit/ui/marketing`). The footer (`SiteFooter`) ends with the theme toggle (when `ENABLE_THEME_TOGGLE` is on) and the language selector (when more than one locale is configured).

## Common Pitfalls

- Linking to pages that don't exist: they render the [404 page](./error-pages).
- Importing server config (`*.config.server.ts`) here: only type imports are allowed; values come from `PublicConfig`.
- A label key that doesn't exist renders as written (e.g. `app.routes.membrs`): check the spelling against `app.json`.
- Adding a settings page to `navigation.config.tsx`: it belongs in `settings-navigation.config.tsx`, and the page needs `export const layout = 'settings'`.
- Treating `visible` as a guard: a hidden settings page still opens by URL unless its loader refuses.

---

**Next:** [Theme and Layout →](./theme)
