The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.
TypeScript b2b-marketplacecomposable-commerceecommerceenterpriseheadless-commercemarketplacemedusamedusajsmulti-vendortypescript
---
title: "Widgets"
sidebarTitle: "Widgets"
description: "Render a React component in a fixed slot on a built-in admin or vendor page."
---
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.
## Create a widget
<Steps>
<Step title="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.
```tsx 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
```
</Step>
<Step title="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.
```tsx 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](#vendor-zones)
for the full list.
</Step>
<Step title="Run the panel">
Start the panel and open the page you targeted. The widget renders in its
zone.
```bash Terminal
bun run dev
```
The vendor panel runs on `http://localhost:7001` and the admin panel on
`http://localhost:7000`.
</Step>
</Steps>
## 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. |
| `label` | `string` (optional) | The tab label, as an i18n key or a literal. Only used by [tab zones](#tabs). |
## 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. |
```tsx
import { Container } from "@medusajs/ui"
import type { HttpTypes } from "@medusajs/types"
const ProductDetailNote = ({ data }: { data?: HttpTypes.AdminProduct }) => (
<Container>{data?.title}</Container>
)
```
<Note>
The public `login.logo`, `login.before`, and `login.after` zones render before
authentication and receive no `data`.
</Note>
## Tabs
Some detail pages group their content into tabs. A tab zone lets a widget add a
tab of its own: the widget's `label` names the tab and its component renders as
the tab's panel. The placement decides whether the tab sits before or after the
built-in ones.
```tsx apps/admin-test/src/widgets/store-loyalty-tab.tsx
import { defineWidgetConfig } from "@mercurjs/dashboard-sdk"
import { Container, Heading } from "@medusajs/ui"
import type { SellerDTO } from "@mercurjs/types"
const StoreLoyaltyTab = ({ data }: { data?: SellerDTO }) => (
<Container>
<Heading level="h2">Loyalty for {data?.name}</Heading>
</Container>
)
export const config = defineWidgetConfig({
zone: "stores.detail.tabs.after",
id: "loyalty",
label: "Loyalty",
})
export default StoreLoyaltyTab
```
A widget that targets a tab zone without a `label` is not shown. `permission`
works as on any other widget and hides the tab from actors who lack it.
| Panel | Tab zone | Page |
| ----- | ------------------- | ------------------------------------------------------- |
| Admin | `stores.detail.tabs` | Store detail, next to Orders, Offers, Users and Time off. |
## List item rows
The locations list renders one card per stock location. The `locations.list.item`
zone sits inside each card, so a widget there adds a row to the card instead of a
separate block above or below the list. `locations.list.item.before` renders
between the card header and the built-in rows, and `locations.list.item.after`
renders after them. `data` is the stock location of that card.
```tsx apps/vendor/src/widgets/location-local-delivery-row.tsx
import { defineWidgetConfig } from "@mercurjs/dashboard-sdk"
import { StatusBadge, Text } from "@medusajs/ui"
import type { HttpTypes } from "@mercurjs/types"
type StockLocation = HttpTypes.VendorStockLocationResponse["stock_location"]
const LocationLocalDeliveryRow = ({ data }: { data?: StockLocation }) => {
const enabled = data?.fulfillment_sets?.some(
(set) => set.type === "local_delivery"
)
return (
<div className="flex items-center justify-between px-6 py-4">
<Text size="small" weight="plus" className="text-ui-fg-subtle flex-1">
Local delivery
</Text>
<div className="flex-1">
<StatusBadge color={enabled ? "green" : "grey"}>
{enabled ? "Enabled" : "Disabled"}
</StatusBadge>
</div>
</div>
)
}
export const config = defineWidgetConfig({
zone: "locations.list.item.after",
})
export default LocationLocalDeliveryRow
```
Return a single row element, without a `Container` of its own. The card draws the
divider between rows.
| Panel | Zone | Page |
| ------ | --------------------- | -------------------------------------- |
| Vendor | `locations.list.item` | Settings → Locations, each location card. |
| Admin | `locations.list.item` | Settings → Locations, each location card. |
## 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` | ✓ | ✓ | ✓ | `list.item` |
| `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` | ✓ | ✓ | ✓ | `list.item` |
| `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` | ✓ | ✓ | | |
<Note>
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.
</Note>
## Next steps
<CardGroup cols={2}>
<Card title="Custom Fields" href="/references/panel-extensions/custom-fields">
Add fields, section rows, and list columns to a built-in model.
</Card>
<Card title="Create a new page" href="/references/panel-extensions/create-page">
Add a route with file-based routing and register it in the sidebar.
</Card>
</CardGroup>