The default Medusa Admin dashboard covers the essentials well: products, orders, customers, and inventory. But most merchants eventually need something the default dashboard was never built to show, whether that is a third party fulfilment status, a custom loyalty score, or a sync indicator for an ERP integration. Rather than forking the admin or building a separate internal tool, Medusa gives you a cleaner path: admin widgets.

This guide walks through building a custom admin widget from scratch, based on the patterns described in Medusa's own admin widget documentation, and covers the decisions that matter once you move past the basic tutorial example.

What Admin Widgets Actually Are

An admin widget is a React component that Medusa injects into a predefined zone inside the existing dashboard layout, such as above a product's details or beside an order summary. You are not replacing a page or maintaining a separate app. You are dropping a component into a slot that Medusa already renders, which means your customisation inherits the dashboard's navigation, authentication, and styling for free.

This matters more than it sounds. Teams that build a fully separate internal admin tool end up duplicating auth logic, duplicating navigation, and eventually maintaining two dashboards that drift out of sync. A widget avoids all three problems by living inside the system merchants already use every day.

There is also a maintainability argument for widgets that is easy to overlook early on. Because widgets are just React components living inside your own Medusa project, they upgrade alongside Medusa itself. A separate internal admin app, by contrast, needs its own dependency updates, its own deployment pipeline, and its own auth token refresh logic, none of which Medusa manages for you. Six months in, the widget approach is almost always the lower maintenance path.

Setting Up the Widget File

Widgets live under a specific directory in your Medusa project and follow a simple export contract: a default exported React component, and a named export called config that tells Medusa which zone to render the widget in.

The component itself uses defineWidgetConfig from the Admin Extension SDK to register its zone. A widget placed in the order.details.after zone, for example, will render just below the standard order details panel, receiving the order's data as a prop automatically so you do not need a separate API call just to know which record you are looking at.

Widgets can also receive their configuration as an array of zones rather than a single string, which is useful when the same block of information is relevant on more than one entity. A widget showing a customer's loyalty tier, for instance, might make sense on both the customer details page and the order details page, and registering both zones avoids maintaining two near identical components.

Choosing the Right Injection Zone

Medusa exposes dozens of injection zones across products, orders, customers, and other core entities, split into list zones and detail zones. Picking the correct one is less about technical constraint and more about matching merchant expectation: a widget showing return eligibility belongs near the order status, not buried at the bottom of a customer profile page.

A common mistake is placing every widget in a before zone because it feels more visible. In practice, that pushes core Medusa data further down the page and trains merchants to scroll past your customisation to get to information they actually need daily. Reserve before zones for anything genuinely urgent, like a stock discrepancy warning, and use after zones for supporting context.

List zones deserve a separate mention because they behave differently from detail zones. A widget in a list zone typically has access to the filtered or paginated set of records currently shown rather than a single record, which makes it a good fit for bulk actions or summary counts, but a poor fit for anything that needs deep detail about one specific item. Trying to force detail level information into a list zone widget usually means firing off a separate API call per row, which slows the list view down noticeably as the catalog grows.

Styling the Widget to Match the Dashboard

Medusa UI ships the same component library the core dashboard is built with, including Container and Heading components, so a widget built with those primitives looks native rather than bolted on. Reaching for a separate design system or hand rolled CSS is technically possible but almost always a mistake, since even small spacing or font inconsistencies make a widget feel like a third party plugin instead of part of the product.

For anything more complex than a static display, such as a form or an action button, keep interaction patterns consistent with the rest of the dashboard too. If every other action in Medusa Admin opens a slide out panel, a widget that opens a full page modal will feel jarring even if it works correctly.

Loading states deserve the same attention as the final rendered widget. A blank space that suddenly populates with content a second later reads as a bug even when it is working exactly as intended. A small skeleton block or a subtle loading indicator, built with the same Medusa UI primitives used elsewhere in the dashboard, keeps the experience feeling intentional rather than unfinished.

Fetching and Displaying Custom Data

Most useful widgets need data that lives outside Medusa's core schema, such as a rating from a support ticket system or a sync timestamp from an external warehouse. The cleanest pattern is exposing that data through a custom API route inside your Medusa application, then calling it from the widget using the same authenticated fetch pattern the rest of the admin uses.

Avoid calling third party APIs directly from the widget's client side code. Routing the request through your own backend keeps API keys off the browser, gives you a place to cache or transform the response, and means a slow third party service degrades gracefully instead of freezing the whole widget while it waits on an external call.

Caching is worth planning for early rather than bolting on later. If a widget pulls a value that rarely changes, such as a customer's lifetime order count from an external CRM, refetching it on every single page load adds unnecessary latency to a page merchants open dozens of times a day. A short lived cache on your custom API route, even a simple in memory one, can cut that load time noticeably without any risk of showing badly stale data.

Testing Before It Reaches Merchants

Because a widget renders inside a shared layout, a rendering error in your component can, in some Medusa versions, affect the surrounding page rather than failing in isolation. Wrapping custom widgets in a basic error boundary is cheap insurance, showing a small fallback message instead of breaking the entire order or product page a merchant is trying to work in.

It is also worth testing widgets with genuinely empty or malformed data, not just the happy path from your development seed data. A widget that assumes a field will always be present will eventually meet a record where it is not, usually during a live demo or, worse, during a merchant's busiest sales period.

Permission checks are the last piece that is easy to forget. Not every merchant user should see every widget, particularly ones surfacing financial or supplier data. Medusa's role based access control extends to custom code, so a widget should check the current user's permissions the same way core dashboard pages do, rather than assuming that anyone who can reach the admin should see everything rendered inside it.

When a Widget Is Not Enough

Sometimes the customisation you need does not fit inside an existing zone at all, such as a completely new settings page or a dedicated reporting view. In those cases, Medusa's UI routes feature lets you add entirely new pages to the admin navigation rather than forcing the content into a widget zone it was never meant for. Our team covers this in more depth on our Medusa.js development page, including how we approach larger admin customisation projects for merchants moving off legacy platforms.

The decision between a widget and a full UI route usually comes down to scope. If the feature enhances a record that already exists, like an order or a product, a widget is almost always the right call. If it is a standalone workflow with its own navigation and state, a UI route gives you the room to build it properly instead of squeezing it into a slot designed for something smaller.

Either way, the same principle holds. Extend the admin dashboard merchants already know, rather than asking them to learn a second tool, and the customisation earns its place instead of becoming another tab nobody opens.