5.10.2. Admin UI Routes

In this chapter, you’ll learn how to create a UI route in the admin dashboard.

What is a UI Route?#

A UI route is a React Component that adds a new page to your admin dashboard. The UI Route can be shown in the sidebar or added as a nested page.

For example, you may add a new page to manage product reviews.

How to Create a UI Route?#

A UI route is created in a file named page.tsx under the src/admin/routes directory. The file’s default export must be the UI route’s React component.

For example, create the file src/admin/routes/custom/page.tsx with the following content:

src/admin/routes/custom/page.tsx
1import { Container, Heading } from "@medusajs/ui"2
3const CustomPage = () => {4  return (5    <Container className="divide-y p-0">6      <div className="flex items-center justify-between px-6 py-4">7        <Heading level="h2">This is my custom route</Heading>8      </div>9    </Container>10  )11}12
13export default CustomPage

The new page’s path is the file’s path relative to src/admin/routes. So, the above UI route is a new page added at the path localhost:9000/app/custom.

Test the UI Route#

To test the UI route, start the Medusa application:

npm
yarn
pnpm

Then, after logging into the admin dashboard, open the page localhost:9000/app/custom to see your custom page.

Show UI Route in the Sidebar#

A UI route file can export a configuration object that indicates a new item must be added in the sidebar linking to the new UI route.

For example:

src/admin/routes/custom/page.tsx
1import { defineRouteConfig } from "@medusajs/admin-sdk"2import { ChatBubbleLeftRight } from "@medusajs/icons"3import { Container, Heading } from "@medusajs/ui"4
5const CustomPage = () => {6  return (7    <Container className="divide-y p-0">8      <div className="flex items-center justify-between px-6 py-4">9        <Heading level="h2">This is my custom route</Heading>10      </div>11    </Container>12  )13}14
15export const config = defineRouteConfig({16  label: "Custom Route",17  icon: ChatBubbleLeftRight,18})19
20export default CustomPage

The configuration object is created using the defineRouteConfig function imported from @medusajs/admin-sdk. It accepts the following properties:

• label: the sidebar item’s label.
• icon: an optional React component used as an icon in the sidebar.

The above example adds a new sidebar item with the label Custom Route and an icon from the Medusa UI Icons package.

Create Settings Page#

To create a page under the settings section of the admin dashboard, create the UI route file under the path src/admin/routes/settings.

For example:

src/admin/routes/settings/custom/page.tsx
1import { defineRouteConfig } from "@medusajs/admin-sdk"2import { Container, Heading } from "@medusajs/ui"3
4const CustomSettingPage = () => {5  return (6    <Container className="divide-y p-0">7      <div className="flex items-center justify-between px-6 py-4">8        <Heading level="h1">Custom Setting Page</Heading>9      </div>10    </Container>11  )12}13
14export const config = defineRouteConfig({15  label: "Custom",16})17
18export default CustomSettingPage

This adds a page under the path /app/settings/custom. An item is also added to the settings sidebar with the label Custom.

Path Parameters#

A UI route can accept path parameters if the name of any of the directories in its path is of the format [param].

For example, create the file src/admin/routes/custom/[id]/page.tsx with the following content:

src/admin/routes/custom/[id]/page.tsx
1import { useParams } from "react-router-dom"2import { Container } from "@medusajs/ui"3
4const CustomPage = () => {5  const { id } = useParams()6
7  return (8    <Container className="divide-y p-0">9      <div className="flex items-center justify-between px-6 py-4">10        <Heading level="h1">Passed ID: {id}</Heading>11      </div>12    </Container>13  )14}15
16export default CustomPage

You access the passed parameter using react-router-dom's useParams hook.

If you run the Medusa application and go to localhost:9000/app/custom/123, you'll see 123 printed in the page.

Admin Components List#

To build admin customizations that match the Medusa Admin's designs and layouts, refer to this guide to find common components.