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 } from "@medusajs/ui"2
3const CustomPage = () => {4  return <Container>This is my custom route</Container>5}6
7export 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 } from "@medusajs/ui"4
5const CustomPage = () => {6  return <Container>This is my custom route</Container>7}8
9export const config = defineRouteConfig({10  label: "Custom Route",11  icon: ChatBubbleLeftRight,12})13
14export 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>7      <Heading level="h1">Custom Setting Page</Heading>8    </Container>9  )10}11
12export const config = defineRouteConfig({13  label: "Custom",14})15
16export 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 <Container>Passed ID: {id}</Container>8}9
10export 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.