4.8.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-shared"2import { Container, Heading } from "@medusajs/ui"3
4// The widget5const ProductWidget = () => {6  return (7    <Container>8      <Heading level="h2">Product Widget</Heading>9    </Container>10  )11}12
13// The widget's configurations14export const config = defineWidgetConfig({15  zone: "product.details.before",16})17
18export default ProductWidget

The widget only shows the heading Product Widget.

Use the defineWidgetConfig function imported from @medusajs/admin-shared 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:

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-shared"2import { Container, Heading } from "@medusajs/ui"3import { 4  DetailWidgetProps, 5  AdminProduct,6} from "@medusajs/types"7
8// The widget9const ProductWidget = ({ 10  data,11}: DetailWidgetProps<AdminProduct>) => {12  return (13    <Container>14      <Heading level="h2">15        Product Widget {data.title}16      </Heading>17    </Container>18  )19}20
21// The widget's configurations22export const config = defineWidgetConfig({23  zone: "product.details.before",24})25
26export 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.

Was this chapter helpful?