<UserButton />

A familiar 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 using the Theme Settings, theming props or plain CSS.

Usage

Make sure you've followed the installation guide for Clerk React or ClerkJS before running the snippets below.

Mounting in your app

Once you set up the desired functionality and look and feel for the <UserButton/> component, all that's left is to render it inside your page. The default rendering is simple but powerful enough to cover most use-cases. The theme configuration (look and feel) that you've set up on the Theme page will work out of the box.

1
import {
2
ClerkProvider,
3
SignIn,
4
SignedOut,
5
UserButton,
6
} from "@clerk/clerk-react";
7
8
const frontendApi = process.env.REACT_APP_CLERK_FRONTEND_API;
9
10
function App() {
11
return (
12
<ClerkProvider frontendApi={frontendApi}>
13
<Header />
14
{/* If the user is signed out, show the SignIn component */}
15
{/* After signing in, the user button will be visible */}
16
<SignedOut>
17
<SignIn />
18
</SignedOut>
19
</ClerkProvider>
20
);
21
}
22
23
function Header() {
24
return (
25
<header>
26
<h1>My application</h1>
27
{/* Mount the UserButton component */}
28
<UserButton />
29
</header>
30
);
31
}
32
33
export default App;

Props

NameDescription
showName?string - 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.
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 a signing out from currently active account (multisession apps) .
afterSwitchSessionUrl?string - Full URL or path to navigate to after a successful account change (multi-session apps).

Customization

The <UserButton/> component can be highly customized through the Instance settings on the Theme page. This document will be updated soon with all necessary details.

© 2022 Clerk. All rights reserved.