The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.
TypeScript b2b-marketplacecomposable-commerceecommerceenterpriseheadless-commercemarketplacemedusamedusajsmulti-vendortypescript
---
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>