4.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.

Nested UI Routes#

Consider that along the UI route above at src/admin/routes/custom/page.tsx you create a nested UI route at src/admin/routes/custom/nested/page.tsx that also exports route configurations:

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

This UI route is shown in the sidebar as an item nested in the parent "Custom Route" item. Nested items are only shown when the parent sidebar items (in this case, "Custom Route") are clicked.

Caveats

Some caveats for nested UI routes in the sidebar:

• Nested dynamic UI routes, such as one created at src/admin/routes/custom/[id]/page.tsx aren't added to the sidebar as it's not possible to link to a dynamic route. If the dynamic route exports route configurations, a warning is logged in the browser's console.
• Nested routes in setting pages aren't shown in the sidebar to follow the admin's design conventions.
• The icon configuration is ignored for the sidebar item of nested UI route to follow the admin's design conventions.

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.