Toolbar Items

Toolbar items appear in the global header bar, next to the breadcrumbs, Dev Mode indicator, and alerts icon. Use them for compact actions that should be available across the Dashboard, such as quick search, a channel-aware shortcut, or a link to a custom help panel.

For page-specific actions, use action bar items instead.

src/plugins/my-plugin/dashboard/index.tsx

import { Button, defineDashboardExtension, useNavigate } from '@vendure/dashboard';import { SearchIcon } from 'lucide-react';function QuickProductSearchButton() {    const navigate = useNavigate();    return (        <Button            variant="ghost"            size="icon"            aria-label="Open products"            onClick={() => void navigate({ to: '/products' })}        >            <SearchIcon className="h-4 w-4" />        </Button>    );}defineDashboardExtension({    toolbarItems: [        {            id: 'quick-product-search',            component: QuickProductSearchButton,            position: { itemId: 'alerts', order: 'before' },        },    ],});

Toolbar components receive no props. Use Dashboard hooks such as useAuth(), useChannel(), usePermissions(), or useNavigate() when the item needs application state.

Positioning

Toolbar items can be positioned relative to built-in toolbar items or to items added by other extensions:

Tsx

defineDashboardExtension({    toolbarItems: [        {            id: 'help',            component: HelpButton,            position: {                itemId: 'alerts',                order: 'after',            },        },    ],});

The built-in toolbar item IDs are:

ID	Description
`dev-mode-indicator`	The Dev Mode badge, visible only when Dev Mode is enabled
`alerts`	The alerts icon

order can be:

Order	Behavior
`before`	Place your item before the target item
`after`	Place your item after the target item
`replace`	Replace the target item with your item

Items without a position are placed before all built-in toolbar items.

Permissions and Conditional Display

Use requiresPermission when the toolbar item should only be available to administrators with specific permissions:

Tsx

defineDashboardExtension({    toolbarItems: [        {            id: 'export-orders',            component: ExportOrdersButton,            position: { itemId: 'alerts', order: 'before' },            requiresPermission: ['ReadOrder'],        },    ],});

Return null from the component when visibility depends on runtime state:

Tsx

import { Button, useChannel } from '@vendure/dashboard';import { BuildingIcon } from 'lucide-react';function ChannelShortcut() {    const { activeChannel } = useChannel();    if (!activeChannel) {        return null;    }    return (        <Button variant="ghost" size="icon" aria-label={activeChannel.code}>            <BuildingIcon className="h-4 w-4" />        </Button>    );}

Enable Dev Mode, then hover the toolbar item you want to target. The popover shows the itemId you can use in position.itemId.

The Extension Targets reference lists the built-in toolbar IDs.

Best Practices

Keep toolbar items icon-sized and provide an accessible label with aria-label.
Use toolbar items for global actions only.
Prefer before or after over replace unless you intentionally want to take ownership of a built-in toolbar action.
Import Dashboard UI components and hooks from @vendure/dashboard.

Was this chapter helpful?

Report Issue

Edited Jun 24, 2026·Edit this page

Toolbar Items

Add a Toolbar Item

Positioning

Permissions and Conditional Display

Finding Toolbar IDs

Best Practices