Skip to content

The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.

13.1 KB
Raw Blame
---
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>