Skip to content

useAuth

useAuth(): AuthState & object

Defined in: react/src/index.tsx:650

Who calls, and how to change it: the client’s AuthState (status, principal and, while signed in, expiresAt) with signIn and signOut forwarded to the client.

It follows the client with useSyncExternalStore, so a component renders again once per change of status, principal or expiresAt and never otherwise (a renewed delegation, or a parent that renders, does not). A session that ends by the clock renders it again with "expired" when its expiresAt passes, with no user activity needed.

"signed-in" may be a read-only session: Internet Identity can scope one to queries, and the network refuses its updates. Nothing tells the two apart yet. The object it returns is the same until the state changes, so it is safe in a dependency array or as a prop of a memoized child.

On a server, and while a page hydrates, the state is anonymous: the server has no session, and rendering the browser’s would not match the server’s HTML. A browser whose state is another one (signed in, or a session that expired or is signed in elsewhere) renders the component again with its own state right after hydration; an anonymous one does not, and keeps the object. A component that reads status before then should show the same thing signed out and while the session is read. Whenever it moves on after hydrating (a signed-in reload, or a session that expired or is signed in elsewhere), it renders a Suspense boundary still dehydrated below it on the client, as for useClient.

signIn and signOut reject like Client.signIn and Client.signOut: on a client built with identity, which has no sign-in, and on a server.

Error outside a ReactorProvider.