<UserButton />

A component that allows users to manage their account, switch accounts, or sign out

Overview

Originally popularized by Google, users have come to expect that little photo of themselves in the top-right of the page – it’s the access point to manage their account, switch accounts, or sign out.

The <UserButton/> component is used to render this familiar user button UI. It renders a clickable user avatar - when clicked, the full UI opens as a popup.

Clerk is the only provider with multi-session support, allowing users to sign into multiple accounts at once and switch between them. For multisession 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.

Control the look and feel of the <UserButton/> component and match it to your application brand using the appearance prop.

Usage

Make sure you've followed the quickstart guide for Clerk Next.js or Clerk React before running the snippets below.

Mounting in your app

Once you set up your desired authentication options and have signed in as a user, you can render the <UserButton/> in your app. The default rendering is simple but powerful enough to cover most use-cases. The theme configuration (look and feel) can be completely customized using the appearance prop.

In this 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.

1
import {
2
  ClerkProvider,
3
  SignedIn,
4
  SignedOut,
5
  SignInButton,
6
  UserButton
7
} from "@clerk/nextjs";
8

9
function Header() {
10
  return (
11
    <header
12
      style={{ display: "flex", justifyContent: "space-between", padding: 20 }}
13
    >
14
      <h1>My App</h1>
15
      <SignedIn>
16
        {/* Mount the UserButton component */}
17
        <UserButton />
18
      </SignedIn>
19
      <SignedOut>
20
        {/* Signed out users get sign in button */}
21
        <SignInButton />
22
      </SignedOut>
23
    </header>
24
  );
25
}
26

27
function MyApp({ pageProps }) {
28
  return (
29
    <ClerkProvider {...pageProps}>
30
      <Header />
31
    </ClerkProvider>
32
  );
33
}
34

35
export default MyApp;

1
import {
2
  ClerkProvider,
3
  SignedIn,
4
  SignedOut,
5
  SignInButton,
6
  UserButton
7
} from "@clerk/clerk-react";
8

9
function Header() {
10
  return (
11
    <header
12
      style={{ display: "flex", justifyContent: "space-between", padding: 20 }}
13
    >
14
      <h1>My App</h1>
15
      <SignedIn>
16
        {/* Mount the UserButton component */}
17
        <UserButton />
18
      </SignedIn>
19
      <SignedOut>
20
        {/* Signed out users get sign in button */}
21
        <SignInButton />
22
      </SignedOut>
23
    </header>
24
  );
25
}
26

27
function App() {
28
  return (
29
    <ClerkProvider publishableKey="clerk-pub-key">
30
      <Header />
31
    </ClerkProvider>
32
  );
33
}
34

35
export default App;

1
<html>
2
<body>
3
    <div id="user-button"></div>
4
    
5
    <script>
6
        const el = document.getElementById("user-button");
7
        // Mount the pre-built Clerk UserButton component
8
        // inside an HTMLElement on your page. 
9
        window.Clerk.mountUserButton(el);
10
    </script>
11
</body>
12
</html>

Redirect to custom profile

By default, clicking Manage account in the <UserButton/> popup menu will open the User Profile as a modal.

You can change this behavior to redirect to your custom user profile page by doing the following:

Mounting <UserProfile/> in your app
Setting the userProfileMode prop to navigation (the default is modal)
Setting the userProfileUrl prop to the full URL of the user profile page

<UserButton
  userProfileMode="navigation"
  userProfileUrl={
    typeof window !== "undefined"
      ? `${window.location.origin}/profile`
      : undefined
  }
/>

If userProfileMode is navigation and userProfileUrl is not provided, clicking Manage account will redirect to the Clerk-hosted user account page.

Props

Name	Type	Description
appearance?	Theme	Controls the overall look and feel
showName?	boolean	Controls if the user name is displayed next to the user image button.
signInUrl?	string	The full URL or path to navigate to when the "Add another account" button is clicked.
userProfileMode	"modal" \| "navigation"	Controls whether clicking the "Manage 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.
userProfileUrl?	string	The full URL or path leading to the user management interface.
afterSignOutUrl?	string	The full URL or path to navigate to after a signing out from all accounts (applies to both single-session and multi-session apps)
afterMultiSessionSingleSignOutUrl?	string	The full URL or path to navigate to after signing out from the currently active account (multisession apps).
afterSwitchSessionUrl?	string	Full URL or path to navigate to after a successful account change (multi-session apps).
defaultOpen	boolean	Controls whether the <UserButton/> should open by default during the first render.
userProfileProps?	UserProfileProps	Specify options for the underlying <UserProfile /> component. e.g. `<UserButton userProfileProps={{additionalOAuthScopes: {google: ['foo', 'bar'], github: ['qux']}}} />`

Customization

The <UserButton/> component can be highly customized through the appearance prop and can be styled using CSS Modules, Tailwind, inline CSS objects, or global CSS.

By leveraging the appearance prop above, it's possible to customize the appearance of the <UserProfile/> component that is presented by clicking the <UserButton/>. Below is a simple example of how that can be achieved:

1
<UserButton
2
 appearance={{
3
   userProfile: { elements: { breadcrumbs: "bg-slate-500" } },
4
 }} />

Example Customization:

1
<UserButton
2
 appearance={{
3
   userProfile: { elements: { breadcrumbs: "bg-slate-500" } },
4
 }} />