5.10.1. Admin Widgets

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

What is an Admin Widget?#

Admin widgets are React components you inject into predetermined injection zones in the Medusa Admin dashboard.

For example, you can add a widget on the order details page that shows payment details retrieved from Stripe.

How to Create a Widget?#

A widget is created in a file under the src/admin/widgets directory. The file’s default export must be the widget, which is the React component. The file must also export the widget’s configurations.

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

The widget only shows the heading Product Widget.

Use the defineWidgetConfig function imported from @medusajs/admin-sdk to create and export the widget's configurations. It accepts as a parameter an object with the following property:

• zone: A string or an array of strings, each being the name of the zone to inject the widget into.

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

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.

Detail Widget Props#

Widgets that are injected into a details page (for example, product.details.before) receive a data prop, which is the main data of the details page (for example, the product object).

For example:

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

Notice that the type of the props is DetailWidgetProps, which accepts as a type argument the expected type of data.

Injection Zone#

Refer to this reference for the full list of injection zones and their props.