Clerk logo

Clerk Docs

Ctrl + K
Go to clerkstage.dev
Check out a preview of our new docs.

<UserButton />

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

Overview

The <UserButton/> component is used to render the familiar user button UI popularized by Google. Learn more about the <UserButton/> component, what it is, and how it is used by reading our User Button component guide.

Embedding a <UserButton /> component

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;

Props

NameTypeDescription
appearance?object

Controls the overall look and feel

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.

userProfileMode"modal" | "navigation"

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.

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).

defaultOpenboolean

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']}}} />

Custom Styling

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.

Customizing User Profile Modal

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
}} />

Localization

The <UserButton/> component can be localized using the localization prop. This allows you to customize the language used within the <UserButton/> component.

Was this helpful?

Clerk © 2023