4.10.1. Admin Widgets

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

What is an Admin Widget?#

The Medusa Admin dashboard's pages are customizable to insert widgets of custom content in pre-defined injection zones. You create these widgets as React components that allow admin users to perform custom actions.

For example, you can add a widget on the product details page that allow admin users to sync products to a third-party service.

How to Create a Widget?#

You create a widget in a .tsx file under the src/admin/widgets directory. The file’s default export must be the widget, which is the React component that renders the custom content. The file must also export 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

You export the ProductWidget component, which shows the heading Product Widget. In the widget, you use Medusa UI, a package that Medusa maintains to allow you to customize the dashboard with the same components used to build it.

To export the widget's configurations, you use the defineWidgetConfig function imported from @medusajs/admin-sdk. It accepts as a parameter an object 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.

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.

Props Passed in Detail Pages#

Widgets that are injected into a details 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 Zone#

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

Admin Components List#

To build admin customizations that match the Medusa Admin's designs and layouts, refer to this guide to find common components.