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	-

---

Widget Requirements

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

1. All widget files must be placed in the folder /src/admin/widgets in your backend directory.
2. A widget file must have a valid React component as its default export.
3. 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"
}

---

How to Create a Widget

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

yarn add @medusajs/admin@beta @medusajs/medusa@beta

pnpm add @medusajs/admin@beta @medusajs/medusa@beta

(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"
  ]
}

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"]
}

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"]
}

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"
  },
  // ...
}

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.

Create the Admin Widget

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

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.

Styling your Widget

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

Widget Props

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

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

yarn add react-router-dom

pnpm add react-router-dom

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

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

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

---

See Also

• How to create admin UI routes
• Create a plugin for your admin customizations