How to Create an Admin Widget
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 |
---|---|---|
| Added at the top of the orders list page | - |
| Added at the bottom of the order list page | - |
| Added at the top of the order details page | Type
|
| Added at the end of the order details page | Type
|
| Added at the top of the draft orders list page | - |
| Added at the bottom of the draft orders list page | - |
| Added at the top of the draft order details page | Type
|
| Added at the bottom of the draft order details page | Type
|
| Added at the top of the customers list page | - |
| Added at the bottom of the customers list page | - |
| Added at the top of the customer details page | Type
|
| Added at the bottom of the customer details page | Type
|
| Added at the top of the customer groups list page | - |
| Added at the bottom of the customer groups list page | - |
| Added at the top of the customer group details page | Type
|
| Added at the bottom of the customer group details page | Type
|
| Added at the top of the product list page | - |
| Added at the bottom of the products list page | - |
| Added at the top of the product details page | Type
|
| Added at the bottom of the product details page | Type
|
| Added at the top of the product collections list page | - |
| Added at the bottom of the product collections list page | - |
| Added at the top of the product collection details page | Type
|
| Added at the bottom of the product collections list page | Type
|
| Added at the top of the “price list” list page | - |
| Added at the bottom of the “price list” list page | - |
| Added at the top of the “price list” details page | Type
|
| Added at the bottom of the “price list” details page | Type
|
| Added at the top of the discounts list page | - |
| Added at the bottom of the discounts list page | - |
| Added at the top of the discounts details page | Type
|
| Added at the bottom of the discount details page | Type
|
| Added at the top of the gift cards list page | - |
| Added at the bottom of the gift cards list page | - |
| Added at the top of the gift card details page | Type
|
| Added at the bottom of the gift card details page | Type
|
| Added at the top of the custom gift card page | Type
|
| Added at the bottom of the custom gift card page | Type
|
| Added before the login form | - |
| 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:
- 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:
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.
(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:
{
"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:
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:
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:
{
// ...
"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:
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:
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.
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:
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
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:
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:
If you're installing it in a plugin with admin customizations, make sure to include it in peerDependencies
.
For example:
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:
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
Custom API Routes
You can also use medusa-react
to interact with custom API Routes using the createCustomAdminHooks utility function.