DefineDashboardExtension

routes

Allows you to define custom routes such as list or detail views.

navSections

Allows you to define custom nav sections for the dashboard.

Can be provided as either:

• An array of DashboardNavSectionDefinition objects to declaratively add new sections
• A function that receives the current NavMenuConfig and returns a new one, allowing full control over the nav menu (move, remove, reorder items between sections)

When using the function form, the function is guaranteed to run after all array-form registrations have completed, so it always sees the fully-populated nav config.

Example

// Array form (existing)navSections: [{ id: 'my-section', title: 'My Section' }]// Function form (new)navSections: (config) => ({    sections: config.sections.map(s =>        s.id === 'settings' && 'items' in s            ? { ...s, items: s.items?.filter(i => i.id !== 'administrators') }            : s    ),})// Function form, deciding per user. The function itself still runs once, at// registration; the predicate it attaches is evaluated on every nav render.navSections: config =>    setNavVisibility(config, { sections: [BUILT_IN_NAV_SECTION_IDS.Catalog] }, ctx => !isFloorStaff(ctx)),

Note: modifier functions should return a new config object rather than mutating the input, to ensure predictable behavior when multiple modifiers are composed. The function form was introduced in version 3.6.0.

pageBlocks

Allows you to define custom page blocks for any page in the dashboard.

actionBarItems

Allows you to define custom action bar items for any page in the dashboard.

alerts

Allows you to define custom alerts that can be displayed in the dashboard.

widgets

Allows you to define custom widgets for the Insights page.

insights

Groups all Insights page extension options, such as custom widgets and code-level widget exclusions.

Example

defineDashboardExtension({    insights: {        widgets: [myWidget],        excludeWidgets: ['latest-orders-widget'],    },});

customFormComponents

Registers custom input component IDs for custom fields and configurable operation arguments.

dataTables

Allows you to customize aspects of existing data tables in the dashboard.

detailForms

Allows you to customize detail pages, including native field input overrides.

login

Allows you to customize the login page with custom components.

historyEntries

Allows a custom component to be used to render a history entry item in the Order or Customer history lists.

refundDestinations

Allows the presentation of a refund destination to be customised in the refund dialog, adding a label, an icon and an optional configuration component. The destination itself is defined on the backend by a RefundDestinationStrategy.

toolbarItems

Allows you to define custom toolbar items in the app shell header bar. Toolbar items appear alongside the breadcrumbs, Dev Mode indicator, and alerts icon.

customProviders

Allows you to add custom providers in different locations.

widgets

Custom widgets to add to the Insights page.

excludeWidgets

The ids of widgets that should be completely removed from the Insights page. Excluded widgets are never rendered, never appear in the user-facing widget picker, and cannot be re-enabled by a user setting. This works for both built-in widgets and widgets registered by other extensions, regardless of registration order.

Example

defineDashboardExtension({    insights: {        excludeWidgets: ['latest-orders-widget'],    },});

filters

Global filters whose components render in the Insights page action bar, next to the built-in date range picker. A filter's value is shared with every widget on the page, which reads it via useWidgetFilters().filters[id]. This lets several widgets filter on a common constraint (for example a selected warehouse). Filter state is session-only.

Example

defineDashboardExtension({    insights: {        filters: [            {                id: 'warehouse',                defaultValue: 'all',                component: WarehouseFilter,            },        ],    },});