How to Add a Widget

A widget is a React component attached to a named zone on a built-in page. You drop one file under src/widgets/, and the SDK renders it at that zone while the rest of the page stays exactly as shipped, including its data fetching, filters, and pagination. This is the lightest way to add UI to a page you don’t own. Reach for it first when you want to add something to an existing screen.

A widget is additive, not a replacement. Unlike a drop-in route, which owns the whole page, a widget layers your component onto the built-in page at a documented zone.

What you’ll build

A tip banner above the vendor product list, rendered from a single file, with the list itself untouched.

Register the typed targets

Widget zones are typed ids that the vendor panel generates from its own pages and ships as @mercurjs/vendor/extension-targets. Register them once so the ids resolve everywhere, with a single ambient reference in your app’s src.

apps/vendor/src/extension-targets.d.ts

/// <reference types="@mercurjs/vendor/extension-targets" />

Projects from create-mercur-app already ship this file. With it present, an invalid zone fails tsc instead of silently doing nothing.

Create the widget file

Drop a file under src/widgets/. Export the component as the default and a config built with defineWidgetConfig. The zone names where it renders.

apps/vendor/src/widgets/product-list-banner.tsx

import { defineWidgetConfig } from "@mercurjs/dashboard-sdk"
import { Container, Text } from "@medusajs/ui"

export const config = defineWidgetConfig({
  zone: "product.list.before",
})

export default function ProductListBanner() {
  return (
    <Container className="mb-2">
      <Text size="small" className="text-ui-fg-subtle">
        Tip: bulk-import products from the Products menu.
      </Text>
    </Container>
  )
}

Understand the zone id

A zone id reads <domain>.<view>.<placement>. The last segment is the placement.

Placement	Effect
`before`	Renders before the built-in content of the zone
`after`	Renders after the built-in content

Multiple before or after widgets on the same zone stack in registration order.

Reload the panel

Start the project and open the vendor portal. Widget files hot-reload. The banner appears above the product list, and the table below it works exactly as before.

Terminal

bun run dev

Available zones

These zones are mounted today in the vendor portal.

Zone	Where it renders
`product.list.before` / `.after`	Vendor product list page
`seller.setup.before` / `.after`	The store-setup and onboarding surface (dashboard home plus store settings), passed the `seller` as `data`
`login.logo.*`	The logo slot on the public login screen
`login.before.` / `login.after.`	Around the login form, rendered before authentication

The full, valid set is typed as WidgetZoneId and generated into @mercurjs/vendor/extension-targets from the panel’s own zone hosts. Let your editor autocomplete zone: to see every option. A zone no page renders can’t be targeted and won’t type-check.

Verify

The tip banner renders above the product list.
Search, filter, and paginate the list. All built-in behavior still works.
Change the zone to product.list.after and reload. The banner moves below the list.
Set zone: "not.a.zone". tsc (bun run lint) fails with a “not assignable to WidgetZoneId” error.
Delete the file. The banner disappears, and nothing else changes.

FAQ

Can a widget target more than one zone?

Can a block ship widgets?

Yes. A block can include src/widgets/ files in its vendor_ui or admin_ui entry, and they’re aggregated just like the host app’s. Installing the block adds the widget with no wiring.

Does the admin panel have widget zones too?

Next steps

Extend forms and tables

Add validated fields and columns with defineCustomFieldsConfig.

Extend the onboarding flow

Add a store-setup field and persist it through a workflow hook.

How-Tos

Integrations

Deployment

What you’ll build

Register the typed targets

Add the widget

Available zones

Verify

FAQ

Next steps

Extend forms and tables

Extend the onboarding flow

​What you’ll build

​Register the typed targets

​Add the widget

​Available zones

​Verify

​FAQ

​Next steps

Extend forms and tables

Extend the onboarding flow

What you’ll build

Register the typed targets

Add the widget

Available zones

Verify

FAQ

Next steps