Docs

<UserButton /> component

Clerk's <UserButton /> component renders the familiar user button UI popularized by Google.

The <UserButton /> component is used to render the familiar user button UI popularized by Google.

Clerk is the only provider with multi-session support, allowing users to sign into multiple accounts at once and switch between them. For multi-session apps, the <UserButton /> automatically supports instant account switching, without the need of a full page reload. For more information, you can check out the Multi-session applications guide.

Properties

All props are optional.

  • Name
    afterMultiSessionSingleSignOutUrl (deprecated)
    Type
    string
    Description

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

  • Name
    afterSignOutUrl (deprecated)
    Type
    string
    Description

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

  • 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 clicking 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.

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.

layout.tsx
import { ClerkProvider, SignedIn, SignedOut, SignInButton, UserButton } from '@clerk/nextjs'

function Header() {
  return (
    <header style={{ display: 'flex', justifyContent: 'space-between', padding: 20 }}>
      <h1>My App</h1>
      <SignedIn>
        {/* Mount the UserButton component */}
        <UserButton />
      </SignedIn>
      <SignedOut>
        {/* Signed out users get sign in button */}
        <SignInButton />
      </SignedOut>
    </header>
  )
}

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <ClerkProvider>
        <Header />
        {children}
      </ClerkProvider>
    </html>
  )
}
userButtonExample.tsx
import { ClerkProvider, SignedIn, SignedOut, SignInButton, UserButton } from '@clerk/nextjs'

function Header() {
  return (
    <header style={{ display: 'flex', justifyContent: 'space-between', padding: 20 }}>
      <h1>My App</h1>
      <SignedIn>
        {/* Mount the UserButton component */}
        <UserButton />
      </SignedIn>
      <SignedOut>
        {/* Signed out users get sign in button */}
        <SignInButton />
      </SignedOut>
    </header>
  )
}

function MyApp({ pageProps }) {
  return (
    <ClerkProvider {...pageProps}>
      <Header />
    </ClerkProvider>
  )
}

export default MyApp
app.tsx
import { ClerkProvider, SignedIn, SignIn, SignUp, UserButton } from '@clerk/clerk-react'
import { BrowserRouter, Route, Routes, useNavigate } from 'react-router-dom'

const clerk_pub_key = process.env.REACT_APP_CLERK_PUBLISHABLE_KEY

function PublicPage() {
  return (
    <>
      <h1>Public page</h1>
      <a href="/protected">Go to protected page</a>
    </>
  )
}

function ProtectedPage() {
  return (
    <>
      <h1>Protected page</h1>
      <UserButton />
    </>
  )
}

function ClerkProviderWithRoutes() {
  const navigate = useNavigate()

  return (
    <ClerkProvider publishableKey={clerk_pub_key} navigate={(to) => navigate(to)}>
      <Routes>
        <Route path="/" element={<PublicPage />} />
        <Route path="/sign-in/*" element={<SignIn routing="path" path="/sign-in" />} />
        <Route path="/sign-up/*" element={<SignUp routing="path" path="/sign-up" />} />
        <Route
          path="/protected"
          element={
            <SignedIn>
              <ProtectedPage />
            </SignedIn>
          }
        />
      </Routes>
    </ClerkProvider>
  )
}

function App() {
  return (
    <BrowserRouter>
      <ClerkProviderWithRoutes />
    </BrowserRouter>
  )
}
router/index.tsx
import { UserButton } from '@clerk/remix'
import { getAuth } from '@clerk/remix/ssr.server'
import { LoaderFunction, redirect } from '@remix-run/node'

export const loader: LoaderFunction = async (args) => {
  const { userId } = await getAuth(args)
  if (!userId) {
    return redirect('/sign-in')
  }
  return {}
}

export default function Index() {
  return (
    <div>
      <h1>Index route</h1>
      <p>You are signed in!</p>
      <UserButton />
    </div>
  )
}
pages/index.astro
---
import { SignedIn, UserButton } from '@clerk/astro/components'
---

<SignedIn>
  <UserButton />
</SignedIn>

Usage with JavaScript

The following methods available on an instance of the Clerk class are used to render and control the <UserButton /> component:

The following examples assume that you have followed the quickstart in order to add Clerk to your JavaScript application.

mountUserButton()

Render the <UserButton /> component to an HTML <div> element.

function mountUserButton(node: HTMLDivElement, props?: UserButtonProps): void

mountUserButton() params

  • Name
    node
    Type
    HTMLDivElement
    Description

    The <div> element used to render in the <UserButton /> component

  • Name
    props?
    Type
    UserButtonProps
    Description

    The properties to pass to the <UserButton /> component

mountUserButton() usage

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

// Initialize Clerk with your Clerk publishable key
const clerk = new Clerk('YOUR_PUBLISHABLE_KEY')
await clerk.load()

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

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

clerk.mountUserButton(userbuttonDiv)
index.html
<!-- Add a <div id="user-button"> element to your HTML -->
<div id="user-button"></div>

<!-- Initialize Clerk with your
Clerk Publishable key and Frontend API URL -->
<script
  async
  crossorigin="anonymous"
  data-clerk-publishable-key="YOUR_PUBLISHABLE_KEY"
  src="https://YOUR_FRONTEND_API_URL/npm/@clerk/clerk-js@latest/dist/clerk.browser.js"
  type="text/javascript"
></script>

<script>
  window.addEventListener('load', async function () {
    await Clerk.load()

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

    Clerk.mountUserButton(userbuttonDiv)
  })
</script>

unmountUserButton()

Unmount and run cleanup on an existing <UserButton /> component instance.

function unmountUserButton(node: HTMLDivElement): void

unmountUserButton() params

  • Name
    node
    Type
    HTMLDivElement
    Description

    The container <div> element with a rendered <UserButton /> component instance.

unmountUserButton() usage

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

// Initialize Clerk with your Clerk publishable key
const clerk = new Clerk('YOUR_PUBLISHABLE_KEY')
await clerk.load()

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

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

clerk.mountUserButton(userButtonDiv)

// ...

clerk.unmountUserButton(userButtonDiv)
index.html
<!-- Add a <div id="user-button"> element to your HTML -->
<div id="user-button"></div>

<!-- Initialize Clerk with your
Clerk Publishable key and Frontend API URL -->
<script
  async
  crossorigin="anonymous"
  data-clerk-publishable-key="YOUR_PUBLISHABLE_KEY"
  src="https://YOUR_FRONTEND_API_URL/npm/@clerk/clerk-js@latest/dist/clerk.browser.js"
  type="text/javascript"
></script>

<script>
  window.addEventListener('load', async function () {
    await Clerk.load()

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

    Clerk.mountUserButton(userButtonDiv)

    // ...

    Clerk.unmountUserButton(userButtonDiv)
  })
</script>

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