Skip to content

The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.

8.5 KB
Raw Blame
---
title: "How to Customize Navigation"
sidebarTitle: "Customize Navigation"
description: "Reorder, hide, relabel, re-parent, and group the panel's built-in sidebar items from a single _navigation.ts file."
---

Reshape the built-in sidebar without replacing it. You author one host-owned file, `src/_navigation.ts`, and it reorders, hides, relabels, and re-parents the built-in items.

The sidebar ships a fixed set of items such as Orders, Products, and Customers. `_navigation.ts` is the single source of truth for their shape. It overrides existing items only, so a new item still comes from a page you add.

<Info>
  **When to use this vs. a `config` export.** New pages you add via [drop-in routes](/rc/resources/tutorials/custom-panel-page) place their own sidebar item through `defineRouteConfig({ label, rank, nested })`. `_navigation.ts` is for the items you *didn't* create, the built-in ones. The two layer cleanly: custom routes place themselves, and `_navigation.ts` reshapes the built-ins.
</Info>

## What you'll build

A vendor sidebar with Orders pinned to the top, Price Lists hidden, and Campaigns moved under Orders.

## Register the typed targets

Nav item ids are typed and generated per panel. Register them once with a single ambient reference in your app's `src`. The `create-mercur-app` scaffold already ships this file.

```typescript apps/vendor/src/extension-targets.d.ts
/// <reference types="@mercurjs/vendor/extension-targets" />
```

With it present, `id` and `nested` autocomplete and an unknown id fails `tsc`.

## Author the navigation file

<Steps>
  <Step title="Create src/_navigation.ts">
    The file is host-owned and underscore-prefixed. Default-export a `defineNavigationConfig` with an `items` array of overrides.

    ```ts apps/vendor/src/_navigation.ts
    import { defineNavigationConfig } from "@mercurjs/dashboard-sdk"

    export default defineNavigationConfig({
      items: [
        { id: "orders", rank: 0 },              // pin to the top
        { id: "price-lists", hidden: true },    // hide from the sidebar
        { id: "campaigns", nested: "orders" },  // re-parent under Orders
      ],
    })
    ```
  </Step>
  <Step title="Know the override fields">
    Each entry targets one built-in item by its stable `id`.

    | Field | Type | Effect |
    |-------|------|--------|
    | `id` | `NavItemId` | **Required.** The built-in item to override, top-level or nested. |
    | `rank` | `number` | Order within its parent, lower first. |
    | `hidden` | `boolean` | Remove it from the sidebar. |
    | `label` | `string` | Relabel with an i18n key or literal. |
    | `icon` | `ComponentType` | Replace its icon. |
    | `nested` | `NavParentId \| null` | Re-parent under another top-level item. `null` promotes a nested item to top level. |
    | `group` | `NavGroupId` | List the item under a [group heading](#group-items-under-headings). |

    `id`, `nested`, and `group` are checked against the panel's generated `NavItemRegistry`, `NavParentRegistry`, and `NavGroupRegistry`.
  </Step>
  <Step title="Reload the panel">
    Open the vendor portal. Orders sits at the top, Price Lists is gone from the menu, and Campaigns now appears under Orders.

    <Note>
      The route for a hidden item stays reachable directly by URL unless you also remove it.
    </Note>
  </Step>
</Steps>

## Common recipes

```ts
export default defineNavigationConfig({
  items: [
    { id: "payouts", label: "Settlements" },        // relabel
    { id: "categories", nested: null, rank: 1 },    // promote a nested item to top level
    { id: "collections", nested: "orders" },        // move a nested item under a different parent
    { id: "inventory", hidden: true },              // hide a built-in
  ],
})
```

## Group items under headings

Declare groups by keyword in `groups`, then assign items to them with `group`. A group renders in whichever sidebar its items live in, and a group with no visible items isn't rendered.

### Main sidebar

The main sidebar ships without groups. Items you assign to a declared group move out of the default list and render below it, under the group's heading.

```ts apps/vendor/src/_navigation.ts
import { defineNavigationConfig } from "@mercurjs/dashboard-sdk"

export default defineNavigationConfig({
  groups: [
    { id: "catalog", label: "Catalog" },
    { id: "finance", label: "Finance" },
  ],
  items: [
    { id: "products", group: "catalog" },
    { id: "inventory", group: "catalog" },
    { id: "payouts", group: "finance" },
  ],
})
```

Only top-level items can be grouped. Nested children follow their parent.

### Settings sidebar

The settings sidebar already lists its items under groups. The admin panel ships `general`, `developer`, and `myAccount`. The vendor portal ships `general`. You can reshape these built-in groups, add your own, and move items between them. Settings items are targeted by their path without the leading slash, such as `settings/users`.

```ts apps/admin/src/_navigation.ts
import { defineNavigationConfig } from "@mercurjs/dashboard-sdk"

export default defineNavigationConfig({
  groups: [
    { id: "integrations", label: "Integrations", rank: 1 }, // new group, after General
    { id: "developer", label: "API" },                      // relabel a built-in group
  ],
  items: [
    { id: "settings/secret-api-keys", group: "integrations" },
    { id: "settings/tax-regions", group: "integrations", rank: 0 },
  ],
})
```

### Group fields

| Field | Type | Effect |
|-------|------|--------|
| `id` | `string` | **Required.** A new keyword to declare a group, or a built-in settings group id to override. |
| `label` | `string` | Heading text. A literal, or an i18n key when `translationNs` is set. Defaults to the `id`. |
| `translationNs` | `string` | i18n namespace used to resolve `label`. |
| `rank` | `number` | Order among groups, lower first. Defaults to declaration order. Built-in settings groups rank `0`, `1`, `2`. |
| `hidden` | `boolean` | Remove the group and its items from the sidebar. |

An item's `group` only accepts a built-in group id or an id declared in the same file's `groups`, so a typo fails `tsc`.

### Group a custom page

A custom page picks its group in its own route config with the same keyword.

```tsx apps/admin/src/routes/settings/webhooks/page.tsx
import type { RouteConfig } from "@mercurjs/dashboard-sdk"

export const config: RouteConfig = {
  label: "Webhooks",
  group: "integrations",
}
```

<Note>
  A page whose group isn't declared falls back to the default placement: the ungrouped list in the main sidebar, or the first group in the settings sidebar.
</Note>

## Verify

1. The top-level order reflects your `rank` values, with `orders` first.
2. `price-lists` no longer appears in the sidebar.
3. `campaigns` renders as a child under Orders.
4. Set `id: "not-an-item"`. `bun run lint` (tsc) fails against `NavItemRegistry`.
5. Delete `_navigation.ts`. The default sidebar returns.

## FAQ

<AccordionGroup>
  <Accordion title="Can an installed block reorder the sidebar?">
    No. Navigation is deliberately host-only. Blocks can ship pages, widgets, and custom fields, but the sidebar order stays a single source of truth in your app's `_navigation.ts`.
  </Accordion>
  <Accordion title="Can a block put its page in a group?">
    Yes. A block's page sets `group` in its route config like any other page. If the host hasn't declared that group, the page falls back to the default placement.
  </Accordion>
  <Accordion title="What ids can I target?">
    Any built-in item, top-level or nested, by its own id, such as `orders`, `products`, `categories`, `collections`, `campaigns`, or `customer-groups`. Let your editor autocomplete `id:` against `NavItemId`. The full set is generated into your panel's `extension-targets.d.ts`.
  </Accordion>
  <Accordion title="Does this work in the admin panel too?">
    Yes. Drop `src/_navigation.ts` in the admin app and reference `@mercurjs/admin/extension-targets`. Each panel ships its own nav id set.
  </Accordion>
  <Accordion title="How do I add a brand-new sidebar item?">
    That's a [drop-in route](/rc/resources/tutorials/custom-panel-page) with a `config` export. `_navigation.ts` only reshapes built-in items, it doesn't create routes.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Add a custom panel page" href="/rc/resources/tutorials/custom-panel-page">
    Add a new screen with its own sidebar item.
  </Card>
  <Card title="Add a widget" href="/rc/resources/tutorials/add-a-widget">
    Inject a component into a built-in page.
  </Card>
</CardGroup>