Add custom pages and links to the <UserProfile /> component

The <UserProfile /> component supports the addition of custom pages and external links to the component's sidenav. It only accepts the following components as children:

• <UserButton.UserProfilePage /> or <UserProfile.Page /> to add a custom page.
• <UserButton.UserProfileLink /> or <UserProfile.Link /> to add a custom link.

You can also reorder default routes.

Before you start

Before you start, it's important to understand how the <UserProfile /> can be accessed:

• As a modal: When a user selects the <UserButton /> component and then selects the Manage account menu item, the <UserProfile /> will open as a modal by default.
• As a dedicated page: You can embed the <UserProfile /> component itself in a dedicated page.

This guide includes examples for both use cases. On the code examples, you can select one of the following two tabs to see the implementation for your preferred use case:

• <UserButton /> tab: By default, the <UserButton /> sets userProfileMode='modal'. If you are using the default settings, then you should select this tab.
• Dedicated page tab: If you do not want the <UserProfile /> to open as a modal, then you should select this tab. For these examples, on the <UserButton /> component, you need to set userProfileMode='navigation' and userProfileUrl='/user-profile'.

Add a custom page

To add a custom page to the <UserProfile /> component, you will need to use one of the following components, depending on the use case mentioned in the Before you start section.

Props

<UserButton.UserProfilePage /> and <UserProfile.Page /> accept the following props, all of which are required:

Example

import { Clerk } from '@clerk/clerk-js'

const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

const clerk = new Clerk(pubKey)
await clerk.load()

document.getElementById('app').innerHTML = `
    <div id="user-profile"></div>
  `

const userProfileDiv = document.getElementById('user-profile')

clerk.mountUserProfile(userProfileDiv, {
  customPages: [
    {
      url: 'custom-page',
      label: 'Custom Page',
      mountIcon: (el) => {
        el.innerHTML = '👋'
      },
      unmountIcon: (el) => {
        el.innerHTML = ''
      },
      mount: (el) => {
        el.innerHTML = `
            <h1><b>Custom Page</b></h1>
            <p>This is the content of the custom page.</p>
            `
      },
      unmount: (el) => {
        el.innerHTML = ''
      },
    },
    {
      url: '/other-page',
      label: 'Other Page',
      mountIcon: (el) => {
        el.innerHTML = '🌐'
      },
      unmountIcon: (el) => {
        el.innerHTML = ''
      },
    },
  ],
})

Add a custom link

Reorder default routes

The <UserProfile /> component includes two default menu items: Account and Security, in that order. You can reorder these default items by setting the label prop to 'account' or 'security'. This will target the existing default item and allow you to rearrange it.

Note that when reordering default routes, the first item in the navigation sidenav cannot be a custom link.

Example

The following example adds a custom page as the first item in the sidenav, followed by a custom link to the homepage, and then the default Account and Security pages.

import { Clerk } from '@clerk/clerk-js'

const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

const clerk = new Clerk(pubKey)
await clerk.load()

document.getElementById('app').innerHTML = `
  <div id="user-profile"></div>
`

const userProfileDiv = document.getElementById('user-profile')

clerk.mountUserProfile(userProfileDiv, {
  customPages: [
    {
      url: 'custom-page',
      label: 'Custom Page',
      mountIcon: (el) => {
        el.innerHTML = '👋'
      },
      unmountIcon: (el) => {
        el.innerHTML = ''
      },
      mount: (el) => {
        el.innerHTML = `
          <h1><b>Custom Page</b></h1>
          <p>This is the content of the custom page.</p>
          `
      },
      unmount: (el) => {
        el.innerHTML = ''
      },
    },
    {
      label: 'account',
    },
    {
      label: 'security',
    },
  ],
})