Navigation

The dashboard provides a flexible navigation system that allows you to add custom navigation sections and menu items. Navigation items are organized into sections that can be placed in either the "Platform" (top) or "Administration" (bottom) areas of the sidebar.

The simplest way to add navigation is to add menu items to existing sections. This is done automatically when you define routes with navMenuItem properties.

tsx

import { defineDashboardExtension } from '@vendure/dashboard';

defineDashboardExtension({
    routes: [
        {
            path: '/my-custom-page',
            component: () => <div>My Custom Page</div>,
            navMenuItem: {
                // The section where this item should appear
                sectionId: 'catalog',
                // Unique identifier for this menu item
                id: 'my-custom-page',
                // Display text in the navigation
                title: 'My Custom Page',
                // Optional: URL if different from path
                url: '/my-custom-page',
            },
        },
    ],
});

Available Section IDs

The dashboard comes with several built-in sections that can receive route navMenuItem entries:

catalog - For product-related functionality
sales - For order management
customers - For customer management
marketing - For promotions and marketing tools
settings - For configuration and admin settings
system - For system tools such as the job queue and scheduled tasks

The Insights entry has the ID insights, but it is a top-level navigation item, not a section with child items. Do not use insights as a route navMenuItem.sectionId.

Finding Section IDs & Ordering

You can find the available IDs & their order value for all navigation sections and items using Dev mode:

You can create entirely new navigation sections with their own icons and ordering:

tsx

import { defineDashboardExtension } from '@vendure/dashboard';
import { FileTextIcon, SettingsIcon } from 'lucide-react';

defineDashboardExtension({
    // Define custom navigation sections
    navSections: [
        {
            id: 'content-management',
            title: 'Content',
            icon: FileTextIcon,
            placement: 'top', // Platform area
            order: 350, // After Sales (300), before Customers (400)
        },
        {
            id: 'integrations',
            title: 'Integrations',
            icon: SettingsIcon,
            placement: 'bottom', // Administration area
            order: 150, // Between System (100) and Settings (200)
        },
    ],
    routes: [
        {
            path: '/articles',
            component: () => <div>Articles</div>,
            navMenuItem: {
                sectionId: 'content-management', // Use our custom section
                id: 'articles',
                title: 'Articles',
            },
        },
        {
            path: '/pages',
            component: () => <div>Pages</div>,
            navMenuItem: {
                sectionId: 'content-management',
                id: 'pages',
                title: 'Pages',
            },
        },
    ],
});

For documentation on all the configuration properties available, see the reference docs:

Section Placement and Ordering

The navigation sidebar is divided into two areas:

Top Placement ('top'): The "Platform" area for core functionality (Dashboard, Catalog, Sales, etc.)
Bottom Placement ('bottom'): The "Administration" area for system and configuration sections (System, Settings)

Placement Examples

tsx

defineDashboardExtension({
    navSections: [
        {
            id: 'reports',
            title: 'Reports',
            icon: BarChartIcon,
            placement: 'top', // Appears in Platform area
            order: 150, // Positioned within top sections
        },
        {
            id: 'integrations',
            title: 'Integrations',
            icon: PlugIcon,
            placement: 'bottom', // Appears in Administration area
            order: 150, // Positioned within bottom sections
        },
    ],
});

Order Scoping

:::important Order Scoping Order values are scoped within each placement area. This means:

Top sections compete only with other top sections for positioning
Bottom sections compete only with other bottom sections for positioning
You can use the same order value in both top and bottom without conflict :::

Default Top-Level Orders

Top Placement (Platform):

Insights: 100
Catalog: 200
Sales: 300
Customers: 400
Marketing: 500

Bottom Placement (Administration):

Settings: 100
System: 200

This means if you want to add a section between Catalog and Sales in the top area, you might use order: 250. If you want to add a section between Settings and System in the bottom area, you could use order: 150.

:::note[Default Placement] If you don't specify a placement, sections default to 'top' placement. :::

The navSections property can also be a function. Use this form when you need full control over the existing navigation structure, including moving, removing, renaming, or reordering built-in sections and items.

The function receives the fully registered navigation config after all array-form navSections and route navMenuItem registrations have been applied. Return a new config object rather than mutating the input.

Remove a built-in item

tsx

import { defineDashboardExtension } from '@vendure/dashboard';

defineDashboardExtension({
    navSections: config => ({
        sections: config.sections.map(section => {
            if (section.id === 'settings' && 'items' in section) {
                return {
                    ...section,
                    items: section.items?.filter(item => item.id !== 'administrators'),
                };
            }
            return section;
        }),
    }),
});

Move items into a new section

tsx

import { defineDashboardExtension } from '@vendure/dashboard';
import { KeyRoundIcon } from 'lucide-react';
import type { NavMenuConfig } from '@vendure/dashboard';

defineDashboardExtension({
    navSections: (config: NavMenuConfig): NavMenuConfig => {
        const idsToMove = ['administrators', 'roles'];
        const settingsSection = config.sections.find(section => section.id === 'settings');
        const settingsItems =
            settingsSection && 'items' in settingsSection ? (settingsSection.items ?? []) : [];

        return {
            sections: [
                ...config.sections.map(section => {
                    if (section.id === 'settings' && 'items' in section) {
                        return {
                            ...section,
                            items: section.items?.filter(item => !idsToMove.includes(item.id)),
                        };
                    }
                    return section;
                }),
                {
                    id: 'access',
                    title: 'Access',
                    icon: KeyRoundIcon,
                    placement: 'bottom',
                    order: 150,
                    items: settingsItems.filter(item => idsToMove.includes(item.id)),
                },
            ],
        };
    },
});

Rename a section

tsx

defineDashboardExtension({
    navSections: config => ({
        sections: config.sections.map(section =>
            section.id === 'catalog' ? { ...section, title: 'Products' } : section,
        ),
    }),
});

Use Dev Mode or the Extension Targets reference to find built-in navigation IDs.

Unauthenticated Routes

By default, all navigation is assumed to be for authenticated routes, i.e. the routes are only accessible to administrators who are logged in.

Sometimes you want to make a certain route accessible to unauthenticated users. For example, you may want to implement a completely custom login page or a password recovery page, which must be accessible to everyone.

This is done by setting authenticated: false in your route definition:

tsx

import { defineDashboardExtension } from '@vendure/dashboard';

defineDashboardExtension({
    routes: [
        {
            path: '/public',
            component: () => (
                <div className="flex h-screen items-center justify-center text-2xl">
                    This is a public page!
                </div>
            ),
            authenticated: false, // [!code highlight]
        },
    ],
});

This page will then be accessible to all users at http://localhost:4873/dashboard/public

Complete Example

Here's a comprehensive example showing how to create a complete navigation structure for a content management system:

tsx

import { defineDashboardExtension } from '@vendure/dashboard';
import { FileTextIcon, ImageIcon, TagIcon, FolderIcon, SettingsIcon } from 'lucide-react';

defineDashboardExtension({
    // Create custom navigation sections
    navSections: [
        {
            id: 'content',
            title: 'Content',
            icon: FileTextIcon,
            placement: 'top', // Platform area
            order: 250, // Between Catalog (200) and Sales (300)
        },
        {
            id: 'media',
            title: 'Media',
            icon: ImageIcon,
            placement: 'top', // Platform area
            order: 275, // After Content section
        },
    ],

    routes: [
        // Content section items
        {
            path: '/articles',
            component: () => <div>Articles List</div>,
            navMenuItem: {
                sectionId: 'content',
                id: 'articles',
                title: 'Articles',
            },
        },
        {
            path: '/pages',
            component: () => <div>Pages List</div>,
            navMenuItem: {
                sectionId: 'content',
                id: 'pages',
                title: 'Pages',
            },
        },
        {
            path: '/categories',
            component: () => <div>Categories List</div>,
            navMenuItem: {
                sectionId: 'content',
                id: 'categories',
                title: 'Categories',
            },
        },

        // Media section items
        {
            path: '/media-library',
            component: () => <div>Media Library</div>,
            navMenuItem: {
                sectionId: 'media',
                id: 'media-library',
                title: 'Library',
            },
        },
        {
            path: '/media-folders',
            component: () => <div>Media Folders</div>,
            navMenuItem: {
                sectionId: 'media',
                id: 'media-folders',
                title: 'Folders',
            },
        },

        // Add to existing settings section
        {
            path: '/cms-settings',
            component: () => <div>CMS Settings</div>,
            navMenuItem: {
                sectionId: 'settings',
                id: 'cms-settings',
                title: 'CMS Settings',
            },
        },
    ],
});

Icons

The dashboard uses Lucide React icons. You can import any icon from the library:

tsx

import {
    HomeIcon,
    ShoppingCartIcon,
    UsersIcon,
    SettingsIcon,
    FileTextIcon,
    ImageIcon,
    BarChartIcon,
    // ... any other Lucide icon
} from 'lucide-react';

Common icons for navigation sections:

Content: FileTextIcon, EditIcon, BookOpenIcon
Media: ImageIcon, FolderIcon, UploadIcon
Analytics: BarChartIcon, TrendingUpIcon, PieChartIcon
Tools: WrenchIcon, SettingsIcon, CogIcon
Integrations: LinkIcon, ZapIcon, PlugIcon

Best Practices

:::tip[Navigation Design Guidelines]

Use descriptive section names: Choose clear, concise names that indicate the section's purpose
Group related functionality: Keep logically related menu items in the same section
Choose appropriate icons: Select icons that clearly represent the section's function
Consider ordering carefully: Place frequently used sections earlier in the navigation
Keep section counts reasonable: Avoid creating too many sections as it can clutter the navigation
Use consistent naming: Follow consistent patterns for menu item names within sections :::

Adding Navigation Items to Existing Sections