Widgets

A widget is a React component that renders in a named slot on a built-in page. Use a widget to show extra information or an action next to the data a page already displays, such as a payout summary on the order detail page. You add a widget by dropping a file into a panel’s src/widgets/ folder. The SDK finds it at build time. There is no manifest to edit and no route to register.

Add a widget file

Create a file anywhere under src/widgets/ in the panel you want to extend. The file name is up to you.

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

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

const ProductListBanner = () => {
  return (
    <Container>
      <Text>Welcome to your catalog.</Text>
    </Container>
  )
}

export default ProductListBanner

Target a zone with `defineWidgetConfig`

Export a config that names the zone to render in. The last segment of the zone id, before or after, sets the placement.

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

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

Zone ids are typed. A zone that does not exist fails tsc (bun run lint), so you cannot target a page that has no slot. See Available zones for the full list.

Run the panel

Start the panel and open the page you targeted. The widget renders in its zone.

Terminal

bun run dev

The vendor panel runs on http://localhost:7001 and the admin panel on http://localhost:7000.

Configuration

defineWidgetConfig takes one object.

Field	Type	Description
`zone`	`WidgetZoneId \| WidgetZoneId[]`	The zone or zones to render in. Multiple widgets in one zone stack in registration order.
`id`	`string` (optional)	A stable id. Derived from the file path at build time when omitted.

Component props

The widget component receives a single prop.

Prop	Type	Description
`data`	`unknown`	The zone’s contextual entity, such as the loaded product on a `product.detail.*` zone. Undefined on list and public zones that have no single entity.

import { Container } from "@medusajs/ui"
import type { HttpTypes } from "@medusajs/types"

const ProductDetailNote = ({ data }: { data?: HttpTypes.AdminProduct }) => (
  <Container>{data?.title}</Container>
)

The public login.logo, login.before, and login.after zones render before authentication and receive no data.

Zone ids

A zone id reads <domain>.<view>.<placement>.

Domain is the page family, such as product, orders, or customers.
View is the surface within that family: list for a list page, or detail.main and detail.side for the two columns of a detail page.
Placement is before or after. It is the last segment and decides whether the widget renders above or below the target.

Each surface in the tables below expands to two zone ids. The product detail main column, for example, gives you product.detail.main.before and product.detail.main.after.

Vendor zones

Widgets in @mercurjs/vendor (apps/vendor) can target these surfaces. Each cell expands to a .before and an .after zone.

Domain	List	Detail main	Detail side	Other
`campaigns`	✓	✓	✓
`categories`	✓	✓	✓
`collections`	✓	✓
`customer-groups`	✓	✓
`customers`	✓	✓	✓
`inventory`	✓	✓	✓
`locations`	✓	✓	✓
`offer-variants`		✓	✓
`offers`	✓	✓	✓
`orders`	✓	✓	✓	`detail.summary`
`payouts`	✓	✓
`price-lists`	✓	✓	✓
`product`	✓	✓	✓
`product-tags`	✓	✓
`product-types`	✓	✓
`product-variants`		✓
`profile`		✓
`promotions`	✓	✓	✓
`regions`	✓	✓
`reservations`	✓	✓	✓
`return-reasons`	✓
`shipping-profiles`	✓	✓
`tax-regions`	✓	✓		`province.detail.main`
`team`	✓

Vendor public and setup zones

These sit outside the list and detail shape. The login.* zones render before authentication and receive no data.

Zone base	Ids	Renders
`login.logo`	`login.logo.before`, `login.logo.after`	Around the logo on the login page.
`login.before`	`login.before.before`, `login.before.after`	Before the login form.
`login.after`	`login.after.before`, `login.after.after`	After the login form.
`seller.setup`	`seller.setup.before`, `seller.setup.after`	Around the store setup step.

Admin zones

Widgets in @mercurjs/admin (apps/admin-test) can target these surfaces. Each cell expands to a .before and an .after zone.

Domain	List	Detail main	Detail side	Other
`api-keys`	✓	✓
`attributes`	✓	✓
`campaigns`	✓	✓	✓
`categories`	✓	✓	✓
`collections`	✓	✓
`commissions`	✓	✓
`customer-groups`	✓	✓
`customers`	✓	✓	✓
`inventory`	✓	✓	✓
`locations`	✓	✓	✓
`marketplace`		✓
`offer-variants`		✓	✓
`offers`	✓	✓	✓
`orders`	✓	✓	✓
`payouts`	✓	✓
`price-lists`	✓	✓	✓
`product`		✓	✓
`products`	✓
`product-tags`	✓	✓
`product-types`	✓	✓
`product-variants`		✓	✓
`profile`		✓
`promotions`	✓	✓	✓
`refund-reasons`	✓
`regions`	✓	✓
`reservation`	✓	✓	✓
`return-reasons`	✓
`sales-channels`	✓	✓
`shipping-option-types`	✓	✓
`shipping-profiles`	✓	✓
`stores`	✓	✓	✓
`tax-regions`	✓	✓		`province.detail.main`
`users`	✓	✓

Admin splits the product list and product detail across two domains. List zones are products.list.* (plural) and detail zones are product.detail.* (singular). Vendor uses product for both. Detail-page reservation zones are reservation.* (singular) in admin and reservations.* (plural) in vendor. Follow the tables above rather than guessing the pluralization.

Overview

Panel extensions

Admin API

Vendor API

Store API

Configuration

Create a widget

Configuration

Component props

Zone ids

Vendor zones

Vendor public and setup zones

Admin zones

Next steps

Custom Fields

Create a new page

​Create a widget

​Configuration

​Component props

​Zone ids

​Vendor zones

​Vendor public and setup zones

​Admin zones

​Next steps

Custom Fields

Create a new page

Create a widget

Configuration

Component props

Zone ids

Vendor zones

Vendor public and setup zones

Admin zones

Next steps