useSessionList

useSessionList() is the headless counterpart to the account switcher in <UserButton>: the accounts signed in on this browser, which one is active, and a setActive to switch. It only carries data when the environment has Multi-session enabled (see Authentication & session configuration); otherwise isEnabled is false and sessions stays empty.

Accounts are grouped per browser by an HttpOnly cookie the server manages, and switching happens server-side; the SDK handles all of it, there’s nothing to wire beyond calling setActive.

setActive changes the signed-in identity, so by default the SDK reloads the page afterwards (to signInUrl, or /) to rebuild caches for the new user. Set onActiveSessionChange on <ToriiProvider> to handle the swap in-page instead (invalidate your own caches there); the reload is skipped when you do.

Not the device list. useSessions() lists the signed-in user’s own sessions across devices, for revoking them. This hook lists the accounts signed in on this browser, for switching between them.

When to use it

• Build your own account switcher instead of the one built into <UserButton>.

Usage

import { useSessionList } from '@torii-js/torii-react';

function AccountSwitcher() {
  const { isEnabled, sessions, setActive, settingActiveId } = useSessionList();

  if (!isEnabled) return null;

  return (
    <ul>
      {sessions.map((s) => (
        <li key={s.id}>
          <button
            disabled={s.current || settingActiveId === s.id}
            onClick={() => setActive(s.id)}
          >
            {s.name ?? s.email ?? s.userId}
            {s.current ? ' (current)' : ''}
          </button>
        </li>
      ))}
    </ul>
  );
}

Returns

Name	Type	Description
isEnabled	boolean	true when the environment has multi-session enabled.
sessions	ClientSessionSummary[]	Accounts signed in on this browser, most recently used first; the entry with current: true is the active one. Empty when multi-session is disabled; use isEnabled to tell that apart from “enabled but no other accounts”. Each carries id, userId, name, email, lastUsedAt, current.
isLoading	boolean	true until the initial session probe resolves (the list is fetched as part of that probe). Settles to false even when the list is empty; a transient probe failure also settles it, leaving the list empty until the next refresh().
error	ToriiError | null	The ToriiError from the last setActive call, or null. refresh never sets this; transient probe failures keep the previous list.
refresh	() => Promise<void>	Re-fetch the list from the server. Transient failures are swallowed (the previous list is kept), so this never surfaces an error.
setActive	(sessionId: string) => Promise<MutationResult<void>>	Switch the active account to the given session. Resolves a MutationResult; check .ok.
settingActiveId	string | null	Id of the session currently being activated via setActive, else null.

Sign-out behaviour

With multi-session enabled, signOut() ends only the current account’s session and automatically switches to the most recently used remaining account; when no accounts remain, the user lands signed out.

TypeScript

import type { UseSessionListReturn, ClientSessionSummary } from '@torii-js/torii-react';