Skip to main content
Some customizations aren’t about one page — they change the panel’s global chrome. For those, the dashboard SDK exposes a small set of named component overrides: you point the plugin config at your own file, and the panel renders your component in place of the built-in one everywhere it appears.
Choose the right tool. A component override replaces one of four global layout slots across the whole panel. If you want to change a single page, re-compose it instead — and if you want to add a new screen, just drop in a route. The decision guide in Extending Panels compares all three.

​
What you’ll build

A vendor portal with custom topbar actions (a help link and a status badge) and a custom main sidebar, configured entirely from vite.config.ts.

​
The available slots

Exactly four layout components can be replaced:
ComponentWhere it renders
MainSidebarPrimary navigation sidebar on every main page
SettingsSidebarSidebar of the /settings section
TopbarActionsAction cluster on the right side of the top bar
StoreSetupThe store setup screen shown to new sellers (vendor portal)
Anything else — a page, a section, a table — is customized through routes and compound components, not through overrides.

​
Set up the override

1

Write the replacement component

Create the component anywhere under src/. It must have a default export:
apps/vendor/src/components/topbar-actions.tsx
import { Badge, Button } from "@medusajs/ui"

export default function TopbarActions() {
  return (
    <div className="flex items-center gap-x-2">
      <Badge size="2xsmall" color="green">
        All systems operational
      </Badge>
      <Button size="small" variant="transparent" asChild>
        <a href="https://help.example.com" target="_blank" rel="noreferrer">
          Help
        </a>
      </Button>
    </div>
  )
}
2

Register it in the Vite config

Component overrides live in the components option of mercurDashboardPlugin, in your panel app’s vite.config.ts. Paths are relative to src/:
apps/vendor/vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { mercurDashboardPlugin } from '@mercurjs/dashboard-sdk'

export default defineConfig({
  plugins: [
    react(),
    mercurDashboardPlugin({
      medusaConfigPath: '../../packages/api/medusa-config.ts',
      components: {
        TopbarActions: 'components/topbar-actions',
        MainSidebar: 'components/main-sidebar',
      },
    }),
  ],
})
The plugin resolves each path at build time and swaps your component in through the virtual:mercur/components module — no runtime registration, no context providers to wire.
3

Restart the dev server

Vite config changes require a restart. After it, your components render everywhere their slots appear.
Build overrides with @medusajs/ui components and Medusa UI color tokens so they match the rest of the panel. The panels ship no other UI library.

​
Verify

  1. Open the vendor portal — the top bar shows your badge and Help link on every page.
  2. Navigate between main pages and /settings — the override applies everywhere its slot renders.
  3. Remove the components entry and restart — the built-in components return. The originals were never modified.

​
FAQ

Only if your sidebar renders them. A MainSidebar override replaces the entire navigation sidebar, including the auto-generated menu items from route config exports — read them from virtual:mercur/menu-items if you want to keep automatic navigation. If you only want to add or reorder items, you don’t need an override at all: the config export on route files (with rank and nested) covers that.
No — these four slots are the complete list. The login flow, forms, and everything page-level are customized through drop-in routes and compound re-composition.
Each panel app has its own vite.config.ts, so overrides are configured per panel. StoreSetup only exists in the vendor portal; the other three slots exist in both.

​
Next steps

Re-compose a built-in page

Change one page’s composition instead of global chrome.

Extending Panels

The full reference for routes, navigation, branding, and overrides.