Session-aware status UI
Display how many sessions are registered for the current user.
Clerk · Hook
useSessionList
useSessionList() exposes the current user's sessions registered on the client device. Use isLoaded to wait for Clerk initialization before reading sessions or using session-management operations.
How it works
Call the hook without arguments and destructure its result. While Clerk initializes, use isLoaded to show a loading state; afterward, sessions contains the current user's registered client-device sessions, and the returned session-management methods can be used when needed.
Syntax
useSessionList()Returns
An object containing isLoaded, sessions, and session-management methods; after loading, sessions is SessionResource[].
Key points
- It provides access to the current user's registered session collection.
- The session list is scoped to sessions registered on the client device.
- isLoaded is the readiness flag for authentication-related data.
- After loading, sessions contains the available session resources.
- The returned API also supports changing the active session or organization.
Common mistakes
- Do not assume isLoaded changes only once: it can become false again while authentication state is updating.
- sessions represents sessions registered on the current client device, not an arbitrary server-side session query.
Example: Read the session list
import { useSessionList } from '@clerk/react'
export default function Home() {
const { isLoaded, sessions } = useSessionList()
if (!isLoaded) return <div>Loading...</div>
return <p>Previous visits: {sessions.length}</p>
}Wait for Clerk to finish loading, then render the number of registered client-device sessions.
When to use it
Session and organization management
Offer controls that change the active session or organization.
Initialization-aware rendering
Show a loading state while Clerk initializes authentication data.
Interview questions
QWhat does useSessionList return?
useSessionList() takes no arguments and returns session-list state and management helpers. The central fields are isLoaded, which indicates whether Clerk has loaded authentication state, and sessions, which contains registered SessionResource objects.
Follow-up: What should the UI do before initialization completes? Render a loading state and avoid reading sessions until isLoaded is true.
QHow should a component safely render the session count?
The hook exposes sessions as a SessionResource[] after loading. Before Clerk finishes loading, the corresponding state may be undefined, so components should gate access with isLoaded.
Follow-up: Why is a length check alone insufficient? Because sessions may not yet be available during the loading phase.
QWhen would you choose this hook?
Use the hook when a React component needs to inspect or manage the current user's sessions registered on the client device. It is useful for session-aware UI such as showing prior visits or offering session-management controls.
Follow-up: How can the UI remain correct during organization switching? Reapply the loading guard because authentication state can temporarily become unavailable.
Related
useSessionsetActiveSessionResource