How to Create an Admin Widgetbeta

beta

In this document, you will learn about what Admin widgets are and how you can create your own.

Overview

Admin Widgets are custom React components that developers create to be injected into predetermined injection zones across the Medusa Admin dashboard.

Widgets allow you to customize the admin dashboard by providing merchants with new features. For example, you can add a widget on the order details page that shows payment details retrieved from Stripe.

This guide explains the available injection zones and how to create an admin widget.

Injection Zones

Injection zones are areas in the admin that you can add widgets into. Widgets can only be added into these areas.

There are different types of injection zones, and the type affects where the Widget is injected. For the different domains such as product, order, and customer there are list and details zones.

Below is a full list of injection zones:

You can learn more about the additional props in the Props section.

Injection Zone Name	Description	Additional Props
`order.list.before`	Added at the top of the orders list page	-
`order.list.after`	Added at the bottom of the order list page	-
`order.details.before`	Added at the top of the order details page	Type `OrderDetailsWidgetProps` imported from `@medusajs/admin` `{ order, // Order object }`
`order.details.after`	Added at the end of the order details page	Type `OrderDetailsWidgetProps` imported from `@medusajs/admin` `{ order, // Order object }`
`draft_order.list.before`	Added at the top of the draft orders list page	-
`draft_order.list.after`	Added at the bottom of the draft orders list page	-
`draft_order.details.before`	Added at the top of the draft order details page	Type `DraftOrderDetailsWidgetProps` imported from `@medusajs/admin` `{ draftOrder, // DraftOrder object }`
`draft_order.details.after`	Added at the bottom of the draft order details page	Type `DraftOrderDetailsWidgetProps` imported from `@medusajs/admin` `{ draftOrder, // DraftOrder object }`
`customer.list.before`	Added at the top of the customers list page	-
`customer.list.after`	Added at the bottom of the customers list page	-
`customer.details.before`	Added at the top of the customer details page	Type `CustomerDetailsWidgetProps` imported from `@medusajs/admin` `{ customer, // Customer object }`
`customer.details.after`	Added at the bottom of the customer details page	Type `CustomerDetailsWidgetProps` imported from `@medusajs/admin` `{ customer, // Customer object }`
`customer_group.list.before`	Added at the top of the customer groups list page	-
`customer_group.list.after`	Added at the bottom of the customer groups list page	-
`customer_group.details.before`	Added at the top of the customer group details page	Type `CustomerGroupDetailsWidgetProps` imported from `@medusajs/admin` `{ customerGroup, // CustomerGroup object }`
`customer_group.details.after`	Added at the bottom of the customer group details page	Type `CustomerGroupDetailsWidgetProps` imported from `@medusajs/admin` `{ customerGroup, // CustomerGroup object }`
`product.list.before`	Added at the top of the product list page	-
`product.list.after`	Added at the bottom of the products list page	-
`product.details.before`	Added at the top of the product details page	Type `ProductDetailsWidgetProps` imported from `@medusajs/admin` `{ product, // Product object }`
`product.details.after`	Added at the bottom of the product details page	Type `ProductDetailsWidgetProps` imported from `@medusajs/admin` `{ product, // Product object }`
`product_collection.list.before`	Added at the top of the product collections list page	-
`product_collection.list.after`	Added at the bottom of the product collections list page	-
`product_collection.details.before`	Added at the top of the product collection details page	-
`product_collection.details.after`	Added at the bottom of the product collections list page	-
`price_list.list.before`	Added at the top of the “price list” list page	-
`price_list.list.after`	Added at the bottom of the “price list” list page	-
`price_list.details.before`	Added at the top of the “price list” details page	Type `PriceListDetailsWidgetProps` imported from `@medusajs/admin` `{ priceList, // PriceList object }`
`price_list.details.after`	Added at the bottom of the “price list” details page	Type `PriceListDetailsWidgetProps` imported from `@medusajs/admin` `{ priceList, // PriceList object }`
`discount.list.before`	Added at the top of the discounts list page	-
`discount.list.after`	Added at the bottom of the discounts list page	-
`discount.details.before`	Added at the top of the discounts details page	Type `DiscountDetailsWidgetProps` imported from `@medusajs/admin` `{ discount, // Discount object }`
`discount.details.after`	Added at the bottom of the discount details page	Type `DiscountDetailsWidgetProps` imported from `@medusajs/admin` `{ discount, // Discount object }`
`gift_card.list.before`	Added at the top of the gift cards list page	-
`gift_card.list.after`	Added at the bottom of the gift cards list page	-
`gift_card.details.before`	Added at the top of the gift card details page	Type `GiftCardDetailsWidgetProps` imported from `@medusajs/admin` `{ giftCard, // Product object }`
`gift_card.details.after`	Added at the bottom of the gift card details page	Type `GiftCardDetailsWidgetProps` imported from `@medusajs/admin` `{ giftCard, // Product object }`
`custom_gift_card.before`	Added at the top of the custom gift card page	Type `GiftCardCustomWidgetProps` imported from `@medusajs/admin` `{ giftCard, // GiftCard object }`
`custom_gift_card.after`	Added at the bottom of the custom gift card page	Type `GiftCardCustomWidgetProps` imported from `@medusajs/admin` `{ giftCard, // GiftCard object }`
`login.before`	Added before the login form	-
`login.after`	Added after the login form	-

A Widget must adhere to a set of criteria that determines if it is valid for injection. These are:

All widget files must be placed in the folder /src/admin/widgets in your backend directory.
A widget file must have a valid React component as its default export.
A widget file must export a config object of type WidgetConfig imported from @medusajs/admin.

WidgetConfig

WidgetConfig is used to determine the configurations of the widget, mainly the injection zones. It’s an object that accepts the property zone, which can be a single or an array of injection zone strings. For example:

{
  zone: "product.details.after"
}
Report Incorrect CodeCopy to Clipboard

In this section, you’ll learn how to create an admin widget.

Prerequisites

It’s assumed you already have a Medusa backend with the admin plugin installed before you move forward with this guide. If not, you can follow this documentation page to install a Medusa project.

Furthermore, Admin Widgets are currently available as a beta feature. So, you must install the beta version of the @medusajs/admin and @medusajs/medusa packages:

npm
Yarn
pnpm

npm install @medusajs/admin@beta @medusajs/medusa@beta
Report Incorrect CodeCopy to Clipboard

yarn add @medusajs/admin@beta @medusajs/medusa@beta
Report Incorrect CodeCopy to Clipboard

pnpm add @medusajs/admin@beta @medusajs/medusa@beta
Report Incorrect CodeCopy to Clipboard

(Optional) TypeScript Preparations

Since Widgets are React components, they should be written in .tsx or .jsx files. If you’re using Typescript, you need to make some adjustments to avoid Typescript errors in your Admin files.

This section provides recommended configurations to avoid any TypeScript errors.

These changes may already be available in your Medusa project. They're included here for reference purposes.

First, update your tsconfig.json with the following configurations:

tsconfig.json

{
  "compilerOptions": {
    "target": "es2019",
    "module": "commonjs",
    "allowJs": true, 
    "checkJs": false, 
    "jsx": "react-jsx", 
    "declaration": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "noEmit": false,
    "strict": false,
    "moduleResolution": "node",
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/"],
  "exclude": [
    "dist",
    "build",
    ".cache",
    "tests",
    "**/*.spec.js",
    "**/*.spec.ts",
    "node_modules",
    ".eslintrc.js"
  ]
}
Report Incorrect CodeCopy to Clipboard

The important changes to note here are the inclusion of the field "jsx": "react-jsx" and the addition of "build" and “.cache” to exclude.

The addition of "jsx": "react-jsx" specified how should TypeScript transform JSX, and excluding build and .cache ensures that TypeScript ignores build and development files.

Next, create the file tsconfig.server.json with the following content:

tsconfig.server.json

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    /* Emit a single file with source maps instead of having a separate file. */
    "inlineSourceMap": true
  },
  "exclude": ["src/admin", "**/*.spec.js"]
}
Report Incorrect CodeCopy to Clipboard

This is the configuration that will be used to transpile your custom backend code, such as services or entities. The important part is that it excludes src/admin as that is where your Admin code will live.

Finally, create the file tsconfig.admin.json with the following content:

tsconfig.admin.json

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "module": "esnext"
  },
  "include": ["src/admin"],
  "exclude": ["**/*.spec.js"]
}
Report Incorrect CodeCopy to Clipboard

This is the configuration that will be used when transpiling your admin code.

(Optional) Update Scripts in package.json

You can optionally update the following scripts in package.json to make your development process easier:

package.json

{
  // ...
  "scripts": {
    "clean": "cross-env ./node_modules/.bin/rimraf dist",
    "build": "cross-env npm run clean && npm run build:server && npm run build:admin",
    "build:server": "cross-env npm run clean && tsc -p tsconfig.server.json",
    "build:admin": "cross-env medusa-admin build",
    "watch": "cross-env tsc --watch",
    "test": "cross-env jest",
    "seed": "cross-env medusa seed -f ./data/seed.json",
    "start": "cross-env npm run build && medusa start",
    "start:custom": "cross-env npm run build && node --preserve-symlinks index.js",
    "dev": "cross-env npm run build:server && medusa develop"
  },
  // ...
}
Report Incorrect CodeCopy to Clipboard

If you have autoRebuild enabled in the options of @medusajs/admin, you shouldn’t include npm run build:admin in the build script. It will lead to the admin being built twice during development.

To create a new admin widget, start by creating the folder src/admin/widgets. This is where your widgets must be located, as explained in the Widgets Requirements section.

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

src/admin/widgets/product-widget.tsx

import type { WidgetConfig } from "@medusajs/admin"

const ProductWidget = () => {
  return (
    <div>
      <h1>Product Widget</h1>
    </div>
  )
}

export const config: WidgetConfig = {
  zone: "product.details.after",
}

export default ProductWidget
Report Incorrect CodeCopy to Clipboard

This file creates a React Component ProductWidget which renders an H1 header. This React Component is the default export in the file, which is one of the Widgets Requirements.

You also export the object config of type WidgetConfig, which is another widget requirement. It indicates that the widget must be injected in the product.details.after zone.

To test out your widget, run the following command in the root backend directory:

npx @medusajs/medusa-cli@latest develop

This command will build your backend and admin, then runs the backend.

Open localhost:7001 in your browser and log in. Then, go to the details page of any product. You should now see your widget at the bottom of the page.

Try making any changes to the component. The development server will hot-reload and your widget will be updated immediately.

Admin Widgets support Tailwind CSS out of the box.

For example, you can update the widget you created earlier to use Tailwind CSS classes:

src/admin/widgets/product-widget.tsx

import type { 
  WidgetConfig,
} from "@medusajs/admin"

const ProductWidget = () => {
  return (
    <div 
      className="bg-white p-8 border border-gray-200 rounded-lg">
      <h1>Product Widget</h1>
    </div>
  )
}

export const config: WidgetConfig = {
  zone: "product.details.after",
}

export default ProductWidget
Report Incorrect CodeCopy to Clipboard

Every widget receives props of the type WidgetProps, which includes the notify prop. The notify prop is an object that includes the following attributes:

success: a function that can be used to show a success message.
error: a function that can be used to show an error message.
warn: a function that can be used to show a warning message.
info: a function that can be used to show an info message.

In addition, some injection zones provide additional props specific to the context of the page. For example, widgets in the product.details.after zone will also receive a product prop, which is an object holding the data of the product being viewed.

You can learn about what additional props each injection zone may receive in the Injection Zone section.

For example, you can modify the widget you created to show the title of the product:

src/admin/widgets/product-widget.tsx

import type { 
  WidgetConfig, 
  ProductDetailsWidgetProps,
} from "@medusajs/admin"

const ProductWidget = ({
  product,
  notify,
}: ProductDetailsWidgetProps) => {
  return (
    <div className="bg-white p-8 border border-gray-200 rounded-lg">
      <h1>Product Widget {product.title}</h1>
      <button 
        className="bg-black rounded p-1 text-white"
        onClick={() => notify.success("success", "You clicked the button!")}
      >
        Click me
      </button>
    </div>
  )
}

export const config: WidgetConfig = {
  zone: "product.details.after",
}

export default ProductWidget
Report Incorrect CodeCopy to Clipboard

Routing Functionalities

If you want to navigate to other pages, link to other pages, or use other routing functionalities, you can use react-router-dom package.

react-router-dom is available as one of the @medusajs/admin dependencies. You can also install it within your project using the following command:

npm
Yarn
pnpm

npm install react-router-dom
Report Incorrect CodeCopy to Clipboard

yarn add react-router-dom
Report Incorrect CodeCopy to Clipboard

pnpm add react-router-dom
Report Incorrect CodeCopy to Clipboard

If you're installing it in a plugin with admin customizations, make sure to include it in peerDependencies.

For example:

src/admin/widgets/product-widget.tsx

import type { WidgetConfig } from "@medusajs/admin"
import { Link } from "react-router-dom"

const ProductWidget = () => {
  return (
    <div
      className="bg-white p-8 border border-gray-200 rounded-lg">
      <h1>Product Widget</h1>
      <Link to={"/a/orders"}>
        View Orders
      </Link>
    </div>
  )
}

export const config: WidgetConfig = {
  zone: "product.details.after",
}

export default ProductWidget
Report Incorrect CodeCopy to Clipboard

View react-router-dom’s documentation for other available components and hooks.

Querying and Mutating Data

You will most likely need to interact with the Medusa backend from your Widgets. To do so, you can utilize the Medusa React package. It contains a collection of queries and mutation built on @tanstack/react-query that lets you interact with the Medusa backend.

Make sure to also install the Medusa React package first if you’re intending to use it, as explained in the Medusa React guide.

For example, you can modify the widget you created to retrieve the tags of a product from the Medusa backend:

src/admin/widgets/product-widget.tsx

import type { ProductDetailsWidgetProps, WidgetConfig } from "@medusajs/admin"
import { useAdminProductTags } from "medusa-react"

const ProductWidget = ({ product }: ProductDetailsWidgetProps) => {
  const { product_tags } = useAdminProductTags({
    id: product.tags.map((tag) => tag.id),
    limit: 10,
    offset: 0,
  })

  return (
    <div className="bg-white p-8 border border-gray-200 rounded-lg">
      <h3 className="text-lg font-medium mb-4">Product Tags</h3>
      <div className="flex flex-wrap">
        {product_tags?.map((tag) => (
          <span
            key={tag.id}
            className="bg-gray-100 text-gray-800 px-2 py-1 rounded-full text-xs mr-2 mb-2"
          >
            {tag.value}
          </span>
        ))}
      </div>
    </div>
  )
}

export const config: WidgetConfig = {
  zone: "product.details.after",
}

export default ProductWidget
Report Incorrect CodeCopy to Clipboard

You can also use medusa-react to interact with custom endpoints using the createCustomAdminHooks utility function.

How to Create an Admin Widgetbeta

Overview

Injection Zones

Widget Requirements

WidgetConfig

How to Create a Widget

Prerequisites

(Optional) TypeScript Preparations

(Optional) Update Scripts in package.json

Create the Admin Widget

Styling your Widget

Widget Props

Routing Functionalities

Querying and Mutating Data

See Also

Overview​

Injection Zones​

Widget Requirements​

WidgetConfig​

How to Create a Widget​

Prerequisites​

(Optional) TypeScript Preparations​

(Optional) Update Scripts in package.json​

Create the Admin Widget​

Styling your Widget​

Widget Props​

Routing Functionalities​

Querying and Mutating Data​

See Also​

Overview

Injection Zones

Widget Requirements

WidgetConfig

How to Create a Widget

Prerequisites

(Optional) TypeScript Preparations

(Optional) Update Scripts in package.json

Create the Admin Widget

Styling your Widget

Widget Props

Routing Functionalities

Querying and Mutating Data

See Also