Skip to main content
Docs

Add custom items and links to the <UserButton /> component

The <UserButton /> component supports custom menu items, allowing the incorporation of app-specific settings or additional functionality.

There are two types of custom menu items available:

You can also reorder default items and conditionally render menu items.

<UserButton.Action>

<UserButton.Action /> allows you to add actions to the <UserButton /> component, like opening a chat or triggering a modal.

Props

<UserButton.Action /> accepts the following props:

  • Name
    label
    Type
    string
    Description

    The name that will be displayed in the menu of the user button.

  • Name
    labelIcon
    Type
    React.ReactElement
    Description

    An icon displayed next to the label in the menu.

  • Name
    open?
    Type
    string
    Description

    The path segment that will be used to open the user profile modal to a specific page.

  • Name
    onClick?
    Type
    void
    Description

    A function to be called when the menu item is clicked.

Examples

Add an action

The following example adds an "Open chat" action to the <UserButton /> component. When a user selects the <UserButton />, there will be an "Open chat" menu item.

To add custom menu items to the <UserButton /> component using the JavaScript SDK, pass the customMenuItems property to the mountUserButton() method, as shown in the following example:

main.js
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-button"></div>
`

const userButtonDiv = document.getElementById('user-button')

clerk.mountUserButton(userButtonDiv, {
  customMenuItems: [
    {
      label: 'Open chat',
      onClick: () => {
        alert('init chat') // your custom event
      },
      mountIcon: (el) => {
        el.innerHTML = '👤'
      },
      unmountIcon: (el) => {},
    },
  ],
})

Add an action and a custom page

The following example adds an "Open help" action to the <UserButton /> component, as well as a custom page titled "Help". When a user selects the <UserButton />, there will be "Open help" and "Help" menu items.

To add custom pages to the <UserProfile /> component using the JavaScript SDK, pass the customPages property to the mountUserProfile() method, as shown in the following example:

main.js
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-button"></div>
  <div id="user-profile"></div>
`

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

clerk.mountUserButton(userButtonDiv, {
  customMenuItems: [
    {
      label: 'Open help',
      onClick: () => {
        window.location.href = '/#/help'
      },
      mountIcon: (el) => {
        el.innerHTML = '👤'
      },
      unmountIcon: (el) => {},
    },
  ],
})

clerk.mountUserProfile(userProfileDiv, {
  customPages: [
    {
      url: '/help',
      label: 'Help',
      mountIcon: (el) => {
        el.innerHTML = '👤'
      },
      unmountIcon: (el) => {
        el.innerHTML = ''
      },
      mount: (el) => {
        el.innerHTML = `
          <h1>Help Page</h1>
          <p>This is the custom help page</p>
          `
      },
      unmount: (el) => {
        el.innerHTML = ''
      },
    },
  ],
})

<UserButton.Link /> allows you to add links to the <UserButton /> component, like custom pages or external URLs.

Props

<UserButton.Link /> accept the following props, all of which are required:

  • Name
    label
    Type
    string
    Description

    The name that will be displayed in the menu of the user button.

  • Name
    labelIcon
    Type
    React.ReactElement
    Description

    An icon displayed next to the label in the menu.

  • Name
    href
    Type
    string
    Description

    The path segment that will be used to navigate to the custom page.

Example

The following example adds a "Create organization" link to the <UserButton /> component. When a user selects the <UserButton />, there will be a "Create organization" menu item.

To add custom menu items to the <UserButton /> component using the JavaScript SDK, pass the customMenuItems property to the mountUserButton() method, as shown in the following example:

main.js
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-button"></div>
`

const userButtonDiv = document.getElementById('user-button')

clerk.mountUserButton(userButtonDiv, {
  customMenuItems: [
    {
      label: 'Create organization',
      href: '/create-organization',
      mountIcon: (el) => {
        el.innerHTML = '👤'
      },
      unmountIcon: (el) => {},
    },
  ],
})

Reorder default items

The <UserButton /> component includes two default menu items: Manage account and Sign out, in that order. You can reorder these default items by setting the label prop to 'manageAccount' or 'signOut'. This will target the existing default item and allow you to rearrange it.

In the following example, the "Sign out" menu item is moved to the top of the menu, a custom "Create organization" link is added as the second menu item, and the "Manage account" menu item is moved to the bottom of the menu.

main.js
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-button"></div>
`

const userButtonDiv = document.getElementById('user-button')

clerk.mountUserButton(userButtonDiv, {
  customMenuItems: [
    {
      label: 'signOut',
    },
    {
      label: 'Create organization',
      href: '/create-organization',
      mountIcon: (el) => {
        el.innerHTML = '👤'
      },
      unmountIcon: (el) => {},
    },
    {
      label: 'manageAccount',
    },
  ],
})

Conditionally render menu items

To conditionally render menu items based on a user's Role or Custom Permissions, you can use the checkAuthorization() method to check if a user is authorized.

In the following example, the "Create organization" menu item will only render if the current user has the org:app:admin permission.

main.js
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-button"></div>
`

const userButtonDiv = document.getElementById('user-button')
// Check if the user is authenticated
if (clerk.isSignedIn) {
  const hasAdminPermission = clerk.session.checkAuthorization({
    permission: 'org:app:admin',
  })

  if (hasAdminPermission) {
    clerk.mountUserButton(userButtonDiv, {
      customMenuItems: [
        {
          label: 'signOut',
        },
        {
          label: 'Create organization',
          href: '/create-organization',
          mountIcon: (el) => {
            el.innerHTML = '👤'
          },
          unmountIcon: (el) => {},
        },
        {
          label: 'manageAccount',
        },
      ],
    })
  } else {
    clerk.mountUserButton(userButtonDiv)
  }
}

Feedback

What did you think of this content?
GitHubEdit on GitHub

Last updated on