161 lines
4.3 KiB
Plaintext
161 lines
4.3 KiB
Plaintext
import { Table } from "docs-ui"
|
||
|
||
export const metadata = {
|
||
title: `${pageNumber} Admin Widgets`,
|
||
}
|
||
|
||
# {metadata.title}
|
||
|
||
<Note type="soon">
|
||
|
||
Admin customizations are coming soon.
|
||
|
||
</Note>
|
||
|
||
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:
|
||
|
||
```tsx title="src/admin/widgets/product-widget.tsx" highlights={[["4", "ProductWidget", "The React component of the product widget."], ["14", "", "The zone to inject the widget to."]]}
|
||
import type { WidgetConfig } from "@medusajs/admin"
|
||
|
||
// The widget
|
||
const ProductWidget = () => {
|
||
return (
|
||
<div>
|
||
<h2>Product Widget</h2>
|
||
</div>
|
||
)
|
||
}
|
||
|
||
// The widget's configurations
|
||
export const config: WidgetConfig = {
|
||
zone: "product.details.after",
|
||
}
|
||
|
||
export default ProductWidget
|
||
```
|
||
|
||
The widget only shows the heading `Product Widget`.
|
||
|
||
In the exported widget’s configurations, you must specify the zone to inject the widget into. The `zone` property can be a string or an array of strings, each being the name of the injection zone.
|
||
|
||
In the example above, the widget is injected after a product’s details.
|
||
|
||
### Test the Widget
|
||
|
||
To test out the widget, start the Medusa application:
|
||
|
||
```bash npm2yarn
|
||
npm run dev
|
||
```
|
||
|
||
Then, open a product’s details page. You’ll find your custom widget at the bottom of the page.
|
||
|
||
---
|
||
|
||
## Using UI Components
|
||
|
||
It’s highly recommended that you use the [Medusa UI package](https://docs.medusajs.com/ui) to match your widget’s design with the rest of the Medusa Admin.
|
||
|
||
For example, you can rewrite the above component to the following:
|
||
|
||
```tsx title="src/admin/widgets/product-widget.tsx"
|
||
import type { WidgetConfig } from "@medusajs/admin"
|
||
import { Container, Heading } from "@medusajs/ui"
|
||
|
||
const ProductWidget = () => {
|
||
return (
|
||
<Container>
|
||
<Heading level="h2">Product Widget</Heading>
|
||
</Container>
|
||
)
|
||
}
|
||
|
||
export const config: WidgetConfig = {
|
||
zone: "product.details.after",
|
||
}
|
||
|
||
export default ProductWidget
|
||
```
|
||
|
||
---
|
||
|
||
## Widget Props
|
||
|
||
A widget receives a `notify` prop, which is an object having the following properties:
|
||
|
||
- `success`: a function that shows a success toast message.
|
||
- `error`: a function that shows an error toast message.
|
||
- `warn`: a function that shows a warning toast message.
|
||
- `info`: a function that shows an info toast message.
|
||
|
||
Each of these functions accepts two parameters: the message’s title, and the message’s content.
|
||
|
||
In addition, some injection zones provide additional props based on the page’s context.
|
||
|
||
For example, you can rewrite the above widget to the following:
|
||
|
||
```tsx title="src/admin/widgets/product-widget.tsx" highlights={[["14", "product.title", "Show the product's title."], ["18", "success", "Show a success toast message on the click of a button."]]}
|
||
import type {
|
||
WidgetConfig,
|
||
ProductDetailsWidgetProps,
|
||
} from "@medusajs/admin"
|
||
import { Container, Heading, Button } from "@medusajs/ui"
|
||
|
||
const ProductWidget = ({
|
||
notify,
|
||
product,
|
||
}: ProductDetailsWidgetProps) => {
|
||
return (
|
||
<Container>
|
||
<Heading level="h2">
|
||
Product Widget {product.title}
|
||
</Heading>
|
||
<Button
|
||
onClick={() =>
|
||
notify.success("Success!", "You clicked the button!")
|
||
}
|
||
className="mt-3"
|
||
>
|
||
Click me
|
||
</Button>
|
||
</Container>
|
||
)
|
||
}
|
||
|
||
export const config: WidgetConfig = {
|
||
zone: "product.details.after",
|
||
}
|
||
|
||
export default ProductWidget
|
||
```
|
||
|
||
Since the widget is in the product’s details page, it receives the product as a prop. The widget now shows the title of the product in the header.
|
||
|
||
It also shows a button that, when you click, shows a success toast message.
|
||
|
||
<Note title="Tip">
|
||
|
||
Admin Widgets support [Tailwind CSS](https://tailwindcss.com/) out of the box.
|
||
|
||
</Note>
|
||
|
||
---
|
||
|
||
## Injection Zone
|
||
|
||
Refer to [this reference](!resources!/admin-widget-injection-zones) for the full list of injection zones and their props.
|