useUser

useUser() returns the current user plus the load/auth flags. The user object carries the identity, the SDK-visible metadata bags (publicMetadata, unsafeMetadata), and an update() method for the one bag the end-user may write.

user is null only when signed out (no session identity). When signed in it is non-null immediately, but its metadata bags (publicMetadata, unsafeMetadata) are empty {} until isLoaded is true, because the /me profile that fills them is still loading. Gate on isLoaded before reading metadata. For a cheap identity-only check with no profile fetch, read useAuth().user.

When to use it

• Display the current user’s identity (user.id) or metadata (user.publicMetadata).
• Let the user edit their own unsafe metadata: user.update({ unsafeMetadata }).

For richer profile management (email change, first/last name, loading flags) use useUserProfile().

Usage

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

function ThemeToggle() {
  const { user, isLoaded, isSignedIn } = useUser();

  if (!isLoaded) return null;
  if (!isSignedIn || !user) return <span>Welcome, guest</span>;

  const theme = (user.unsafeMetadata.theme as string) ?? 'light';
  return (
    <button
      onClick={() =>
        user.updateUnsafeMetadata({ theme: theme === 'light' ? 'dark' : 'light' })
      }
    >
      Theme: {theme}
    </button>
  );
}

Returns

useUser() throws if called outside a <ToriiProvider>.

Name	Type	Description
user	ToriiUser | null	The current user; null only when signed out. When signed in it is non-null immediately, but its metadata bags stay empty {} until isLoaded is true.
isLoaded	boolean	true once the session probe and (when signed in) the profile fetch have settled.
isSignedIn	boolean	true when the user has an active session with no pending gates.

ToriiUser

Field	Type	Description
id	string	User id (JWT sub).
environmentId	string	Environment the user authenticated against (JWT pid).
emailVerified	boolean	Whether the primary email is verified.
publicMetadata	Record<string, unknown>	Read-only here; server-written, SDK-readable.
unsafeMetadata	Record<string, unknown>	End-user readable and writable.
update(fields)	(fields: UpdateProfileFields) => Promise<…>	Update writable profile fields, incl. unsafeMetadata.
updateUnsafeMetadata(metadata)	(metadata: Record<string, unknown>) => Promise<…>	Deep-merge into the unsafe bag (a key set to null is removed).

Only unsafeMetadata is writable from the SDK. publicMetadata and privateMetadata are server-managed (privateMetadata is never exposed to the SDK at all).

TypeScript

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