Skip to main content
Docs

<UserButton /> component

The <UserButton /> component renders the familiar user button UI popularized by Google.

The <UserButton /> component renders the familiar user button UI popularized by Google. When selected, it opens a dropdown menu with options to manage account settings and sign out. The "Manage account" option launches the <UserProfile /> component, providing access to profile and security settings.

For users that have multi-session enabled, the <UserButton /> also allows users to sign into multiple accounts at once and instantly switch between them without the need for a full page reload. Learn more here.

Properties

The <UserButton /> component accepts the following properties, all of which are optional:

  • Name
    afterMultiSessionSingleSignOutUrl (deprecated)
    Type
    string
    Description

    Deprecated. Move afterMultiSessionSingleSignOutUrl to <ClerkProvider />. The full URL or path to navigate to after signing out from a currently active account in a multi-session app.

  • Name
    afterSignOutUrl (deprecated)
    Type
    string
    Description

    Deprecated. Move afterSignOutUrl to <ClerkProvider />. The full URL or path to navigate to after a successful sign-out.

  • Name
    afterSwitchSessionUrl
    Type
    string
    Description

    The full URL or path to navigate to after a successful account change in a multi-session app.

  • Name
    appearance
    Type
    Appearance | undefined
    Description

    Optional object to style your components. Will only affect Clerk components and not Account Portal pages.

  • Name
    defaultOpen
    Type
    boolean
    Description

    Controls whether the <UserButton /> should open by default during the first render.

  • Name
    showName
    Type
    boolean
    Description

    Controls if the user name is displayed next to the user image button.

  • Name
    signInUrl
    Type
    string
    Description

    The full URL or path to navigate to when the Add another account button is clicked. It's recommended to use the environment variable instead.

  • Name
    userProfileMode
    Type
    'modal' | 'navigation'
    Description

    Controls whether selecting the Manage your account button will cause the <UserProfile /> component to open as a modal, or if the browser will navigate to the userProfileUrl where <UserProfile /> is mounted as a page. Defaults to: 'modal'.

  • Name
    userProfileProps
    Type
    object
    Description

    Specify options for the underlying <UserProfile /> component. For example: {additionalOAuthScopes: {google: ['foo', 'bar'], github: ['qux']}}.

  • Name
    userProfileUrl
    Type
    string
    Description

    The full URL or path leading to the user management interface.

  • Name
    fallback?
    Type
    ReactNode
    Description

    An optional element to be rendered while the component is mounting.

Usage with frameworks

In the following example, <UserButton /> is mounted inside a header component, which is a common pattern on many websites and applications. When the user is signed in, they will see their avatar and be able to open the popup menu.

src/layouts/root-layout.tsx
import { SignedIn, UserButton, SignInButton, SignedOut } from '@clerk/chrome-extension'

export default function Header() {
  return (
    <header>
      <SignedIn>
        <UserButton />
      </SignedIn>
      <SignedOut>
        <SignInButton />
      </SignedOut>
    </header>
  )
}

Customization

To learn about how to customize Clerk components, see the customization documentation.

You can also add custom actions and links to the <UserButton /> menu.

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on