4.2. Admin Widgets

In this chapter, you’ll learn about widgets and how to use them.

What is an Admin Widget?#

The Medusa Admin's pages are customizable for inserting widgets of custom content in pre-defined injection zones. For example, you can add a widget on the product details page that allows admin users to sync products to a third-party service.

You create these widgets as React components that render the content and functionality of the widget.

How to Create a Widget?#

You create a widget in a .tsx file under the src/admin/widgets directory. The file must export:

1. A React component that renders the widget. This will be the file's default export.
2. The widget’s configurations indicating where to insert the widget.

For example, create the file src/admin/widgets/product-widget.tsx with the following content:

src/admin/widgets/product-widget.tsx
1import { defineWidgetConfig } from "@medusajs/admin-sdk"2import { Container, Heading } from "@medusajs/ui"3
4// The widget5const ProductWidget = () => {6  return (7    <Container className="divide-y p-0">8      <div className="flex items-center justify-between px-6 py-4">9        <Heading level="h2">Product Widget</Heading>10      </div>11    </Container>12  )13}14
15// The widget's configurations16export const config = defineWidgetConfig({17  zone: "product.details.before",18})19
20export default ProductWidget

In the example above, the widget is injected at the top of a product’s details.

You export the ProductWidget component, which displays the heading Product Widget. In the widget, you use Medusa UI to customize the dashboard with the same components used to build it.

To export the widget's configuration, you use defineWidgetConfig from the Admin Extension SDK. It accepts an object as a parameter with the zone property, whose value is a string or an array of strings, each being the name of the zone to inject the widget into.

Test the Widget#

To test out the widget, start the Medusa application:

npm
yarn
pnpm

Then, open a product’s details page. You’ll find your custom widget at the top of the page.

Props Passed to Widgets on Detail Pages#

Widgets that are injected into a detail page receive a data prop, which is the main data of the details page.

For example, a widget injected into the product.details.before zone receives the product's details in the data prop:

src/admin/widgets/product-widget.tsx
1import { defineWidgetConfig } from "@medusajs/admin-sdk"2import { Container, Heading } from "@medusajs/ui"3import { 4  DetailWidgetProps, 5  AdminProduct,6} from "@medusajs/framework/types"7
8// The widget9const ProductWidget = ({ 10  data,11}: DetailWidgetProps<AdminProduct>) => {12  return (13    <Container className="divide-y p-0">14      <div className="flex items-center justify-between px-6 py-4">15        <Heading level="h2">16          Product Widget {data.title}17        </Heading>18      </div>19    </Container>20  )21}22
23// The widget's configurations24export const config = defineWidgetConfig({25  zone: "product.details.before",26})27
28export default ProductWidget

The props type is DetailWidgetProps, and it accepts as a type argument the expected type of data. For the product details page, it's AdminProduct.

Injection Zones List#

Refer to the Admin Widget Injection Zones reference for the full list of injection zones and their props.

Admin Components List#

While the Medusa Admin uses the Medusa UI components, it also expands on them for styling and design purposes.

To build admin customizations that match the Medusa Admin's designs and layouts, refer to the Admin Components guide. You'll find components like Header, JSON View, and more that match the Medusa Admin's design.

Show Widgets Conditionally#

In some cases, you may want to show a widget only if certain conditions are met. For example, you may want to show a widget only if the product has a brand.

To prevent the widget from showing, return an empty fragment from the widget component:

src/admin/widgets/product-widget.tsx
1import { defineWidgetConfig } from "@medusajs/admin-sdk"2import { Container, Heading } from "@medusajs/ui"3import { 4  DetailWidgetProps, 5  AdminProduct,6} from "@medusajs/framework/types"7
8// The widget9const ProductWidget = ({ 10  data,11}: DetailWidgetProps<AdminProduct>) => {12  if (!data.metadata?.brand) {13    return <></> // Don't show the widget if the product has no brand14  }15
16  return (17    <Container className="divide-y p-0">18      <div className="flex items-center justify-between px-6 py-4">19        <Heading level="h2">20          Brand: {data.metadata.brand}21        </Heading>22      </div>23    </Container>24  )25}26
27// The widget's configurations28export const config = defineWidgetConfig({29  zone: "product.details.before",30})31
32export default ProductWidget

In the above example, you return an empty fragment if the product has no brand. Otherwise, you show the brand name in the widget.