# Navigation menu

> The sidebar menu of a product with many pages, with titled sections, sub menus that open in place, and counts.

Products with many pages, such as the Loka Musik admin, group the menu into titled sections and fold related pages under a parent. The menu lives in the sidebar of the [Dashboard](https://design.sosialoka.tech/patterns/dashboard/) frame; this page sets how it grows.

## When to use

- Add sections once the menu has more than about seven entries. Name each one after the work it holds, such as "Keuangan & Royalti".
- Add a parent when three or more pages belong together, such as the reports. Two related pages stay as pages.
- A product with five to seven pages keeps the plain list of the Dashboard frame.

### Do and don't

- **Do:** Keep the menu to two levels: a parent and its pages.
- **Don't:** Don't nest a sub menu in a sub menu; turn that level into tabs on the page.

_Live preview of the React and Vue versions: https://design.sosialoka.tech/patterns/navigation-menu/_

## Anatomy

1. Section label
2. Page with a count
3. Parent, open
4. Sub menu with a guide line
5. Current page

The menu sits on the `sidebar` surface. Section labels use `muted-foreground` in `text-xs`. The current page, also inside a sub menu, uses `sidebar-accent`. A sub menu hangs from its parent on a `border` guide line.

## Rules

- **Two levels at most:** a parent and its pages. A deeper area becomes tabs inside its page.
- **A parent is not a page.** It only opens and closes its sub menu and has no `href`. When the area needs an overview, make it the first page, such as "Ringkasan".
- **Open on arrival:** a parent opens by itself when one of its pages is the current page, and its title turns semibold.
- **Open more than one:** opening a parent doesn't close the others.
- **Counts:** a badge shows how many things wait, such as open tickets. Show it on the page; on a closed parent, show the sum. Leave out zero.
- **Order:** sections run from daily work to setup: overview, operations, clients, money, then system. Settings and administration go last.
- **Icons:** first-level pages and parents have an icon; sub menu pages don't.
- **Icons only:** when the sidebar collapses to icons, a parent opens its pages in a menu beside the rail.
- **Phones:** the whole menu moves into the sheet, with the same sections and sub menus.

## Props

The Dashboard block's `nav` takes pages, parents and sections:

| Entry | Shape | Use |
| --- | --- | --- |
| Page | `{ title, href, icon?, active?, badge? }` | A page. `active` marks the current page; `badge` is a count. |
| Parent | `{ title, icon?, items, badge? }` | Opens a sub menu of pages. No `href`. |
| Section | `{ label, items }` | A titled part of the menu, holding pages and parents. |

Pass a list of sections, or a list of pages and parents for a menu without titles. Vue uses the same shapes; Flutter builds the menu from widgets.

## Code

**React**
```tsx
import {
  BuildingIcon,
  CoinsIcon,
  FileTextIcon,
  LayoutDashboardIcon,
  LifeBuoyIcon,
  MegaphoneIcon,
  MusicIcon,
  PercentIcon,
  SettingsIcon,
  ShieldIcon,
  TruckIcon,
} from "lucide-react"
import { DashboardShell, type DashboardNavSection } from "@/components/blocks/dashboard-shell"
import { Card, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"

// The Loka Musik admin menu: titled sections, pages, and parents that open a sub menu.
const nav: DashboardNavSection[] = [
  {
    label: "Overview & Support",
    items: [
      { title: "Dasbor", href: "#dasbor", icon: LayoutDashboardIcon },
      { title: "Tiket Support", href: "#tiket", icon: LifeBuoyIcon, badge: 3 },
      { title: "Pengumuman", href: "#pengumuman", icon: MegaphoneIcon },
    ],
  },
  {
    label: "Katalog & Operasional",
    items: [
      { title: "Pengiriman", href: "#pengiriman", icon: TruckIcon, badge: 12 },
      {
        title: "Laporan",
        icon: FileTextIcon,
        items: [
          { title: "Rilisan", href: "#laporan-rilisan" },
          { title: "Laporan Pengiriman", href: "#laporan-pengiriman" },
          { title: "Laporan Trek", href: "#laporan-trek" },
        ],
      },
    ],
  },
  {
    label: "Manajemen Klien & Artis",
    items: [
      { title: "Klien", href: "#klien", icon: BuildingIcon },
      {
        title: "Artis",
        icon: MusicIcon,
        items: [
          { title: "Artis", href: "#artis" },
          { title: "Klien Artis", href: "#klien-artis" },
          { title: "Kandidat Premium", href: "#kandidat" },
        ],
      },
    ],
  },
  {
    label: "Keuangan & Royalti",
    items: [
      {
        title: "Royalti",
        icon: CoinsIcon,
        items: [
          { title: "Ringkasan", href: "#royalti" },
          { title: "Laporan Royalti", href: "#laporan-royalti", active: true },
          { title: "Unggah Laporan", href: "#unggah" },
          { title: "Penarikan", href: "#penarikan", badge: 5 },
        ],
      },
      {
        title: "Pajak",
        icon: PercentIcon,
        items: [
          { title: "Klien PPh21", href: "#pph21" },
          { title: "Pengaturan PPh21", href: "#pph21-pengaturan" },
        ],
      },
    ],
  },
  {
    label: "Sistem & Master Data",
    items: [
      {
        title: "Pengaturan",
        icon: SettingsIcon,
        items: [
          { title: "Opsi", href: "#opsi" },
          { title: "Template Email", href: "#template-email" },
        ],
      },
      {
        title: "Administrasi",
        icon: ShieldIcon,
        items: [
          { title: "Manajemen Staf", href: "#staf" },
          { title: "Log Aktivitas", href: "#log" },
        ],
      },
    ],
  },
]

export default function NavigationMenuDemo() {
  return (
    <DashboardShell
      nav={nav}
      labels={{ search: "Cari rilis, artis, atau dokumen", empty: "Tidak ada yang cocok.", account: "Akun {name}", menu: "Buka menu" }}
      logo={
        <span className="flex items-center gap-2 font-semibold">
          <span className="size-7 rounded-md bg-primary" />
          Loka Musik Admin
        </span>
      }
      account={{
        name: "Raka Pratama",
        initials: "RP",
        detail: "raka@contoh.id",
        menu: [{ label: "Profil" }, { label: "Keluar", destructive: true }],
      }}
      search={{ groups: [{ heading: "Menu", items: [{ label: "Laporan Royalti" }, { label: "Penarikan" }] }] }}
    >
      <h1 className="text-2xl font-semibold">Laporan Royalti</h1>
      <p className="mt-1 text-sm text-muted-foreground">Laporan dari aggregator yang sudah diunggah.</p>
      <div className="mt-6 grid gap-4 md:grid-cols-3">
        {[
          ["Laporan bulan ini", "18"],
          ["Menunggu diproses", "4"],
          ["Total pendapatan", "Rp182.430.000,00"],
        ].map(([label, value]) => (
          <Card key={label}>
            <CardHeader>
              <CardDescription>{label}</CardDescription>
              <CardTitle className="text-2xl tabular-nums">{value}</CardTitle>
            </CardHeader>
          </Card>
        ))}
      </div>
    </DashboardShell>
  )
}
```

**Vue**
```vue
<script setup lang="ts">
import { Building, Coins, FileText, LayoutDashboard, LifeBuoy, Megaphone, Music, Percent, Settings, Shield, Truck } from "@lucide/vue"
import type { DashboardNavSection } from "@/components/blocks/dashboard-shell"
import { DashboardShell } from "@/components/blocks/dashboard-shell"
import { Card, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"

// The Loka Musik admin menu: titled sections, pages, and parents that open a sub menu.
const nav: DashboardNavSection[] = [
  {
    label: "Overview & Support",
    items: [
      { title: "Dasbor", href: "#dasbor", icon: LayoutDashboard },
      { title: "Tiket Support", href: "#tiket", icon: LifeBuoy, badge: 3 },
      { title: "Pengumuman", href: "#pengumuman", icon: Megaphone },
    ],
  },
  {
    label: "Katalog & Operasional",
    items: [
      { title: "Pengiriman", href: "#pengiriman", icon: Truck, badge: 12 },
      {
        title: "Laporan",
        icon: FileText,
        items: [
          { title: "Rilisan", href: "#laporan-rilisan" },
          { title: "Laporan Pengiriman", href: "#laporan-pengiriman" },
          { title: "Laporan Trek", href: "#laporan-trek" },
        ],
      },
    ],
  },
  {
    label: "Manajemen Klien & Artis",
    items: [
      { title: "Klien", href: "#klien", icon: Building },
      {
        title: "Artis",
        icon: Music,
        items: [
          { title: "Artis", href: "#artis" },
          { title: "Klien Artis", href: "#klien-artis" },
          { title: "Kandidat Premium", href: "#kandidat" },
        ],
      },
    ],
  },
  {
    label: "Keuangan & Royalti",
    items: [
      {
        title: "Royalti",
        icon: Coins,
        items: [
          { title: "Ringkasan", href: "#royalti" },
          { title: "Laporan Royalti", href: "#laporan-royalti", active: true },
          { title: "Unggah Laporan", href: "#unggah" },
          { title: "Penarikan", href: "#penarikan", badge: 5 },
        ],
      },
      {
        title: "Pajak",
        icon: Percent,
        items: [
          { title: "Klien PPh21", href: "#pph21" },
          { title: "Pengaturan PPh21", href: "#pph21-pengaturan" },
        ],
      },
    ],
  },
  {
    label: "Sistem & Master Data",
    items: [
      {
        title: "Pengaturan",
        icon: Settings,
        items: [
          { title: "Opsi", href: "#opsi" },
          { title: "Template Email", href: "#template-email" },
        ],
      },
      {
        title: "Administrasi",
        icon: Shield,
        items: [
          { title: "Manajemen Staf", href: "#staf" },
          { title: "Log Aktivitas", href: "#log" },
        ],
      },
    ],
  },
]

const account = {
  name: "Raka Pratama",
  initials: "RP",
  detail: "raka@contoh.id",
  menu: [{ label: "Profil" }, { label: "Keluar", destructive: true }],
}
const search = { groups: [{ heading: "Menu", items: [{ label: "Laporan Royalti" }, { label: "Penarikan" }] }] }
const labels = { search: "Cari rilis, artis, atau dokumen", empty: "Tidak ada yang cocok.", account: "Akun {name}", menu: "Buka menu" }
const stats = [
  ["Laporan bulan ini", "18"],
  ["Menunggu diproses", "4"],
  ["Total pendapatan", "Rp182.430.000,00"],
]
</script>

<template>
  <DashboardShell :nav="nav" :account="account" :search="search" :labels="labels">
    <template #logo>
      <span class="flex items-center gap-2 font-semibold">
        <span class="size-7 rounded-md bg-primary" />
        Loka Musik Admin
      </span>
    </template>
    <h1 class="text-2xl font-semibold">Laporan Royalti</h1>
    <p class="mt-1 text-sm text-muted-foreground">Laporan dari aggregator yang sudah diunggah.</p>
    <div class="mt-6 grid gap-4 md:grid-cols-3">
      <Card v-for="[label, value] in stats" :key="label">
        <CardHeader>
          <CardDescription>{{ label }}</CardDescription>
          <CardTitle class="text-2xl tabular-nums">{{ value }}</CardTitle>
        </CardHeader>
      </Card>
    </div>
  </DashboardShell>
</template>
```

**Flutter**
```dart
// The navigation menu of a product with many pages, such as the Loka Musik admin: titled sections, pages,
// and parents that open a sub menu in place. A parent is not a page; it opens on its own when one of its
// pages is the current page. Put this column in the sidebar of the dashboard frame.
import 'package:flutter/widgets.dart';
import 'package:shadcn_ui/shadcn_ui.dart';
import 'package:sosialoka_ui/sosialoka_ui.dart';

class _Page {
  const _Page(this.title, {this.icon, this.active = false, this.badge});
  final String title;
  final IconData? icon;
  final bool active;
  final int? badge;
}

class _Parent {
  const _Parent(this.title, this.icon, this.pages);
  final String title;
  final IconData icon;
  final List<_Page> pages;
}

const _sections = <(String, List<Object>)>[
  ('Overview & Support', [
    _Page('Dasbor', icon: LucideIcons.layoutDashboard),
    _Page('Tiket Support', icon: LucideIcons.lifeBuoy, badge: 3),
  ]),
  ('Katalog & Operasional', [
    _Page('Pengiriman', icon: LucideIcons.truck, badge: 12),
    _Parent('Laporan', LucideIcons.fileText, [_Page('Rilisan'), _Page('Laporan Pengiriman'), _Page('Laporan Trek')]),
  ]),
  ('Keuangan & Royalti', [
    _Parent('Royalti', LucideIcons.coins, [
      _Page('Ringkasan'),
      _Page('Laporan Royalti', active: true),
      _Page('Unggah Laporan'),
      _Page('Penarikan', badge: 5),
    ]),
    _Parent('Pajak', LucideIcons.percent, [_Page('Klien PPh21'), _Page('Pengaturan PPh21')]),
  ]),
];

class NavigationMenuDemo extends StatelessWidget {
  const NavigationMenuDemo({super.key});

  @override
  Widget build(BuildContext context) {
    final theme = ShadTheme.of(context);
    return Container(
      width: 256,
      padding: const EdgeInsets.all(8),
      decoration: BoxDecoration(
        color: theme.colorScheme.card,
        border: Border(right: BorderSide(color: theme.colorScheme.border)),
      ),
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.stretch,
        mainAxisSize: MainAxisSize.min,
        children: [
          for (final (label, entries) in _sections) ...[
            Padding(
              padding: const EdgeInsets.fromLTRB(8, 12, 8, 4),
              child: Text(label, style: theme.textTheme.small.copyWith(color: theme.colorScheme.mutedForeground, fontSize: 12)),
            ),
            for (final entry in entries)
              if (entry is _Parent) _ParentEntry(parent: entry) else _PageEntry(page: entry as _Page),
          ],
        ],
      ),
    );
  }
}

class _PageEntry extends StatelessWidget {
  const _PageEntry({required this.page, this.indent = false});

  final _Page page;
  final bool indent;

  @override
  Widget build(BuildContext context) {
    final theme = ShadTheme.of(context);
    final c = context.sosialoka;
    return Semantics(
      selected: page.active,
      child: ShadButton.ghost(
        height: indent ? 32 : 36,
        mainAxisAlignment: MainAxisAlignment.start,
        backgroundColor: page.active ? c.primarySoft : null,
        foregroundColor: page.active ? c.primaryText : theme.colorScheme.foreground,
        leading: page.icon == null ? null : Icon(page.icon, size: 16),
        trailing: page.badge == null ? null : Text('${page.badge}', style: theme.textTheme.small.copyWith(fontSize: 12)),
        onPressed: () {},
        child: Expanded(child: Text(page.title, overflow: TextOverflow.ellipsis)),
      ),
    );
  }
}

class _ParentEntry extends StatefulWidget {
  const _ParentEntry({required this.parent});

  final _Parent parent;

  @override
  State<_ParentEntry> createState() => _ParentEntryState();
}

class _ParentEntryState extends State<_ParentEntry> {
  // A parent opens on its own when one of its pages is the current page.
  late bool _open = widget.parent.pages.any((p) => p.active);

  @override
  Widget build(BuildContext context) {
    final theme = ShadTheme.of(context);
    return Column(
      crossAxisAlignment: CrossAxisAlignment.stretch,
      children: [
        Semantics(
          expanded: _open,
          child: ShadButton.ghost(
            mainAxisAlignment: MainAxisAlignment.start,
            foregroundColor: theme.colorScheme.foreground,
            leading: Icon(widget.parent.icon, size: 16),
            trailing: AnimatedRotation(
              turns: _open ? 0.25 : 0,
              duration: const Duration(milliseconds: 200),
              child: const Icon(LucideIcons.chevronRight, size: 16),
            ),
            onPressed: () => setState(() => _open = !_open),
            child: Expanded(child: Text(widget.parent.title)),
          ),
        ),
        if (_open)
          Container(
            margin: const EdgeInsets.only(left: 15),
            padding: const EdgeInsets.only(left: 9),
            decoration: BoxDecoration(border: Border(left: BorderSide(color: theme.colorScheme.border))),
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.stretch,
              children: [for (final page in widget.parent.pages) _PageEntry(page: page, indent: true)],
            ),
          ),
      ],
    );
  }
}
```

## Install

The menu is part of the Dashboard block; install it from [Dashboard](https://design.sosialoka.tech/patterns/dashboard/#install).

## Accessibility

- A parent is a button with `aria-expanded` and `aria-controls` pointing at its sub menu.
- The current page has `aria-current="page"`, inside a sub menu too.
- A section label names its group of links.
- A count is read with its page, such as "Tiket Support 3".
