diff --git a/docs/authentication/configuration/session-options.mdx b/docs/authentication/configuration/session-options.mdx
index 65644e5cb4..e5bc92a5e0 100644
--- a/docs/authentication/configuration/session-options.mdx
+++ b/docs/authentication/configuration/session-options.mdx
@@ -68,6 +68,16 @@ To enable multi-session in your application, you need to configure it in the Cle
1. Toggle on **Multi-session handling**.
1. Select **Save**.
+### Add multi-session support to your app
+
+
+ It's highly recommended to wrap your application in the [``](/docs/components/control/multi-session) component. This guarantees a full rerendering cycle every time the current session and user changes.
+
+
+
+ You can pass the `afterMultiSessionSingleSignOutUrl` property to [``](/docs/components/clerk-provider) to specify where to navigate to after signing out from a currently active account in a multi-session app.
+
+
There are two main ways to add the multi-session feature to your application:
- Use the [``](/docs/components/user/user-button) component if you want to use a prebuilt UI.
diff --git a/docs/components/clerk-provider.mdx b/docs/components/clerk-provider.mdx
index 1acf20a3ec..eb244c42ee 100644
--- a/docs/components/clerk-provider.mdx
+++ b/docs/components/clerk-provider.mdx
@@ -47,9 +47,9 @@ The recommended approach is to wrap your entire app with `` at th
```tsx {{ filename: 'index.tsx' }}
import React from 'react'
- import ReactDOM from 'react-dom'
+ import ReactDOM from 'react-dom/client'
+ import App from './App.tsx'
import { ClerkProvider } from '@clerk/clerk-react'
- import App from './App'
// Import your Publishable Key
const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY
@@ -58,13 +58,12 @@ The recommended approach is to wrap your entire app with `` at th
throw new Error('Add your Clerk Publishable Key to the .env.local file')
}
- ReactDOM.render(
+ ReactDOM.createRoot(document.getElementById('root')!).render(
-
+ ,
- document.getElementById('root'),
)
```
diff --git a/docs/components/control/multi-session.mdx b/docs/components/control/multi-session.mdx
index af92fce5a0..29a2566bfa 100644
--- a/docs/components/control/multi-session.mdx
+++ b/docs/components/control/multi-session.mdx
@@ -9,28 +9,49 @@ The `` provides a wrapper for your React application tha
- ```tsx {{ filename: 'pages/_app.tsx' }}
- import '@/styles/globals.css'
- import { MultisessionAppSupport, ClerkProvider } from '@clerk/nextjs/internal'
- import { AppProps } from 'next/app'
-
- function MyApp({ Component, pageProps }: AppProps) {
- return (
-
-
-
-
-
- )
- }
+
+ ```tsx {{ filename: 'app/layout.tsx' }}
+ import React from 'react'
+ import { ClerkProvider, MultisessionAppSupport } from '@clerk/nextjs'
- export default MyApp
- ```
+ export default function RootLayout({ children }: { children: React.ReactNode }) {
+ return (
+
+
+
+ {children}
+
+
+
+ )
+ }
+ ```
+
+ ```tsx {{ filename: 'pages/_app.tsx' }}
+ import { ClerkProvider, MultisessionAppSupport } from '@clerk/nextjs'
+ import type { AppProps } from 'next/app'
+
+ function MyApp({ Component, pageProps }: AppProps) {
+ return (
+
+
+
+
+
+ )
+ }
+
+ export default MyApp
+ ```
+
- ```tsx {{ filename: 'app.tsx' }}
- import { ClerkProvider, MultisessionAppSupport } from '@clerk/clerk-react/internal'
+ ```tsx {{ filename: 'index.tsx' }}
+ import React from 'react'
+ import ReactDOM from 'react-dom/client'
+ import App from './App.tsx'
+ import { ClerkProvider, MultisessionAppSupport } from '@clerk/clerk-react'
// Import your Publishable Key
const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY
@@ -39,19 +60,15 @@ The `` provides a wrapper for your React application tha
throw new Error('Add your Clerk Publishable Key to the .env.local file')
}
- function App() {
- return (
-
+ ReactDOM.createRoot(document.getElementById('root')!).render(
+
+
-
+
- )
- }
-
- function Page() {
- return
The content
- }
+ ,
+ )
```
diff --git a/docs/components/user/user-button.mdx b/docs/components/user/user-button.mdx
index 8661255f01..f5b5ba3e3f 100644
--- a/docs/components/user/user-button.mdx
+++ b/docs/components/user/user-button.mdx
@@ -1,23 +1,25 @@
---
title: '`` component'
description: Clerk's component is used to render the familiar user button UI popularized by Google.
+search:
+ rank: 1
---
{{ style: { maxWidth: '436px' } }}
-The `` component is used to render the familiar user button UI popularized by Google.
+The `` component renders the familiar user button UI popularized by Google. When selected, it opens a dropdown menu with options to manage account settings and sign out. The "Manage account" option launches the [``](/docs/components/user/user-profile) component, providing access to profile and security settings.
-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 `` automatically supports instant account switching, without the need of a full page reload. For more information, see the [dedicated guide on multi-session apps](/docs/custom-flows/multi-session-applications#overview).
+For users that have [multi-session](/docs/authentication/configuration/session-options#multi-session-applications) enabled, the `` also allows users to sign into multiple accounts at once and instantly switch between them without the need for a full page reload. Learn more [here](/docs/authentication/configuration/session-options#multi-session-applications).
## Properties
-All props are optional.
+The `` component accepts the following properties, all of which are **optional**:
- `afterMultiSessionSingleSignOutUrl` (deprecated)
- `string`
- **Deprecated. Move `afterMultiSessionSingleSignOutUrl` to [``](/docs/components/clerk-provider).** The full URL or path to navigate to after a signing out from a currently active account in a multi-session app.
+ **Deprecated. Move `afterMultiSessionSingleSignOutUrl` to [``](/docs/components/clerk-provider).** The full URL or path to navigate to after signing out from a currently active account in a multi-session app.
---
@@ -105,11 +107,9 @@ In the following example, `` is mounted inside a header component,
My App
- {/* Mount the UserButton component */}
- {/* Signed out users get sign in button */}
@@ -136,11 +136,9 @@ In the following example, `` is mounted inside a header component,
My App
- {/* Mount the UserButton component */}
- {/* Signed out users get sign in button */}
@@ -162,7 +160,7 @@ In the following example, `` is mounted inside a header component,
```tsx {{ filename: 'src/App.tsx' }}
- import { SignedIn, UserButton } from '@clerk/clerk-react'
+ import { SignedIn, UserButton, SignInButton, SignedOut } from '@clerk/clerk-react'
export default function App() {
return (
@@ -170,6 +168,9 @@ In the following example, `` is mounted inside a header component,
+
+
+
)
}
@@ -179,18 +180,21 @@ In the following example, `` is mounted inside a header component,
```astro {{ filename: 'pages/index.astro' }}
---
- import { SignedIn, UserButton } from '@clerk/astro/components'
+ import { SignedIn, UserButton, SignInButton, SignedOut } from '@clerk/astro/components'
---
+
+
+
```
```tsx {{ filename: 'router/index.tsx' }}
- import { SignedIn, UserButton } from '@clerk/remix'
+ import { SignedIn, UserButton, SignInButton, SignedOut } from '@clerk/remix'
import { getAuth } from '@clerk/remix/ssr.server'
import { LoaderFunction, redirect } from '@remix-run/node'
@@ -214,6 +218,9 @@ In the following example, `` is mounted inside a header component,
+
+
+
)
}
@@ -222,7 +229,7 @@ In the following example, `` is mounted inside a header component,
```tsx {{ filename: 'app/routes/index.tsx' }}
- import { SignedIn, UserButton } from '@clerk/tanstack-start'
+ import { SignedIn, UserButton, SignInButton, SignedOut } from '@clerk/tanstack-start'
import { createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/')({
@@ -235,6 +242,9 @@ In the following example, `` is mounted inside a header component,
+
+
+
)
}
@@ -244,7 +254,7 @@ In the following example, `` is mounted inside a header component,
```vue {{ filename: 'header.vue' }}
@@ -252,105 +262,110 @@ In the following example, `` is mounted inside a header component,
+
+
+
```
-## Usage with JavaScript
+
+ ## Usage with JavaScript
-The following methods available on an instance of the [`Clerk`](/docs/references/javascript/clerk/clerk) class are used to render and control the `` component:
+ The following methods available on an instance of the [`Clerk`](/docs/references/javascript/clerk/clerk) class are used to render and control the `` component:
-- [`mountUserButton()`](#mount-user-button)
-- [`unmountUserButton()`](#unmount-user-button)
+ - [`mountUserButton()`](#mount-user-button)
+ - [`unmountUserButton()`](#unmount-user-button)
-The following examples assume that you have followed the [quickstart](/docs/quickstarts/javascript) in order to add Clerk to your JavaScript application.
+ The following examples assume that you have followed the [quickstart](/docs/quickstarts/javascript) in order to add Clerk to your JavaScript application.
-### `mountUserButton()`
+ ### `mountUserButton()`
-Render the `` component to an HTML `
` element used to render in the `` component
+ The `
` element used to render in the `` component
- ---
+ ---
- - `props?`
- - [`UserButtonProps`](#properties)
+ - `props?`
+ - [`UserButtonProps`](#properties)
- The properties to pass to the `` component
-
+ The properties to pass to the `` component
+
-#### `mountUserButton()` usage
+ #### `mountUserButton()` usage
-```js {{ filename: 'main.js', mark: [15] }}
-import { Clerk } from '@clerk/clerk-js'
+ ```js {{ filename: 'main.js', mark: [15] }}
+ import { Clerk } from '@clerk/clerk-js'
-// Initialize Clerk with your Clerk Publishable Key
-const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY
+ // Initialize Clerk with your Clerk Publishable Key
+ const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY
-const clerk = new Clerk(clerkPubKey)
-await clerk.load()
+ const clerk = new Clerk(clerkPubKey)
+ await clerk.load()
-document.getElementById('app').innerHTML = `
-
-`
+ document.getElementById('app').innerHTML = `
+
+ `
-const userbuttonDiv = document.getElementById('user-button')
+ const userbuttonDiv = document.getElementById('user-button')
-clerk.mountUserButton(userbuttonDiv)
-```
+ clerk.mountUserButton(userbuttonDiv)
+ ```
-### `unmountUserButton()`
+ ### `unmountUserButton()`
-Unmount and run cleanup on an existing `` component instance.
+ Unmount and run cleanup on an existing `` component instance.
-```typescript
-function unmountUserButton(node: HTMLDivElement): void
-```
+ ```typescript
+ function unmountUserButton(node: HTMLDivElement): void
+ ```
-#### `unmountUserButton()` params
+ #### `unmountUserButton()` params
-
- - `node`
- - [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement)
+
+ - `node`
+ - [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement)
- The container `
` element with a rendered `` component instance.
-
+ The container `
` element with a rendered `` component instance.
+
-#### `unmountUserButton()` usage
+ #### `unmountUserButton()` usage
-```js {{ filename: 'main.js', mark: [19] }}
-import { Clerk } from '@clerk/clerk-js'
+ ```js {{ filename: 'main.js', mark: [19] }}
+ import { Clerk } from '@clerk/clerk-js'
-// Initialize Clerk with your Clerk Publishable Key
-const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY
+ // Initialize Clerk with your Clerk Publishable Key
+ const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY
-const clerk = new Clerk(clerkPubKey)
-await clerk.load()
+ const clerk = new Clerk(clerkPubKey)
+ await clerk.load()
-document.getElementById('app').innerHTML = `
-
-`
+ document.getElementById('app').innerHTML = `
+
+ `
-const userButtonDiv = document.getElementById('user-button')
+ const userButtonDiv = document.getElementById('user-button')
-clerk.mountUserButton(userButtonDiv)
+ clerk.mountUserButton(userButtonDiv)
-// ...
+ // ...
-clerk.unmountUserButton(userButtonDiv)
-```
+ clerk.unmountUserButton(userButtonDiv)
+ ```
+
## Customization
diff --git a/docs/custom-flows/sign-out.mdx b/docs/custom-flows/sign-out.mdx
index bab75003c1..1d50fd9025 100644
--- a/docs/custom-flows/sign-out.mdx
+++ b/docs/custom-flows/sign-out.mdx
@@ -7,7 +7,7 @@ description: Learn how to use the Clerk API to build a custom sign-out flow usin
Clerk's [``](/docs/components/user/user-button) and [``](/docs/components/unstyled/sign-out-button) components provide an out-of-the-box solution for signing out users. However, if you're building a custom solution, you can use the [`signOut()`](/docs/references/javascript/clerk/clerk#sign-out) function to handle the sign-out process.
-The `signOut()` function signs a user out of all sessions in a [multi-session application](/docs/custom-flows/multi-session-applications), or only the current session in a single-session context. You can also specify a specific session to sign out by passing the `sessionId` parameter.
+The `signOut()` function signs a user out of all sessions in a [multi-session application](/docs/authentication/configuration/session-options#multi-session-applications), or only the current session in a single-session context. You can also specify a specific session to sign out by passing the `sessionId` parameter.
> [!NOTE]
> The sign-out flow deactivates only the current session. Other valid sessions associated with the same user (e.g., if the user is signed in on another device) will remain active.
diff --git a/docs/references/javascript/clerk/clerk.mdx b/docs/references/javascript/clerk/clerk.mdx
index e272cab8a3..108479c302 100644
--- a/docs/references/javascript/clerk/clerk.mdx
+++ b/docs/references/javascript/clerk/clerk.mdx
@@ -486,7 +486,7 @@ All props below are optional.
### `signOut()`
-- In a [multi-session application](/docs/custom-flows/multi-session-applications): Signs out the active user from all sessions
+- In a [multi-session application](/docs/authentication/configuration/session-options#multi-session-applications): Signs out the active user from all sessions
- In a single-session context: Signs out the active user from the current session
The current client will be deleted. You can specify a specific session to sign out by passing the `sessionId` parameter.
diff --git a/docs/references/javascript/session.mdx b/docs/references/javascript/session.mdx
index 7a0b0fb3f5..f478a00b07 100644
--- a/docs/references/javascript/session.mdx
+++ b/docs/references/javascript/session.mdx
@@ -9,7 +9,7 @@ The `Session` object includes methods for recording session activity and ending
As soon as a [`User`](/docs/references/javascript/user/user) signs in, Clerk creates a `Session` for the current [`Client`][client-ref]. Clients can have more than one sessions at any point in time, but only one of those sessions will be **active**.
-In certain scenarios, a session might be replaced by another one. This is often the case with [multi-session applications](/docs/custom-flows/multi-session-applications).
+In certain scenarios, a session might be replaced by another one. This is often the case with [multi-session applications](/docs/authentication/configuration/session-options#multi-session-applications).
All sessions that are **expired**, **removed**, **replaced**, **ended** or **abandoned** are not considered valid.
diff --git a/public/images/ui-components/user-button.png b/public/images/ui-components/user-button.png
index 086b64787e..45677670a2 100644
Binary files a/public/images/ui-components/user-button.png and b/public/images/ui-components/user-button.png differ
diff --git a/public/images/ui-components/user-button.svg b/public/images/ui-components/user-button.svg
index 9d294082c5..46f108fba6 100644
--- a/public/images/ui-components/user-button.svg
+++ b/public/images/ui-components/user-button.svg
@@ -1,161 +1,161 @@
-