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
    appearance
    Type
    Appearance | undefined
    Description

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

  • 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
    userProfileUrl
    Type
    string
    Description

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

  • Name
    afterSignOutUrl
    Type
    string
    Description

    The full URL or path to navigate to after a signing out from all accounts (applies to both single-session and multi-session apps). Default is /.

  • Name
    afterMultiSessionSingleSignOutUrl
    Type
    string
    Description

    The full URL or path to navigate to after a signing out from currently active account (multi-session apps).

  • Name
    afterSwitchSessionUrl
    Type
    string
    Description

    The full URL or path to navigate to after a successful account change (multi-session apps).

  • Name
    defaultOpen
    Type
    boolean
    Description

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

  • Name
    userProfileProps
    Type
    object
    Description

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

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>
  );
}

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.

Feedback

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