Overview

The @better-auth-ui/react package ships the data layer behind every Better Auth UI component. It's built on TanStack Query and exposes two kinds of primitives per endpoint:

• Hooks — useSession, useSignInEmail, useUpdateUser, …
• Options factories — sessionOptions, signInEmailOptions, updateUserOptions, …

Every hook is a thin wrapper around useQuery or useMutation plus its matching options factory. Use the hook in components, and use the factory anywhere TanStack Query takes a queryOptions / mutationOptions object (useQuery, useQueries, prefetchQuery, useIsMutating, loaders, a global MutationCache, …).

Prerequisites

Wrap your app with a QueryClientProvider above <AuthProvider>.

npm install @tanstack/react-query

Cache keys

All keys are prefixed with "auth". Per-user reads are nested under ["auth", "user", userId, ...] so they're cleared automatically when the user signs out or switches account. Mutation keys (authMutationKeys.signIn.email, authMutationKeys.updateUser, …) are stable and match-friendly for useIsMutating or a global MutationCache observer.

Read a key off the factory for cache seeding or invalidation:

sessionOptions(authClient).queryKey
signInEmailOptions(authClient).mutationKey

Or pull from the shared key factories in @better-auth-ui/core:

import { authQueryKeys, authMutationKeys } from "@better-auth-ui/core"

queryClient.invalidateQueries({ queryKey: authQueryKeys.session })
useIsMutating({ mutationKey: authMutationKeys.signIn.all })

Escape hatches

For Better Auth endpoints that don't have a purpose-built hook yet, use the generic wrappers:

• useAuthQuery(authFn, queryKey, options?) / authQueryOptions(authFn, queryKey, params?) — read-style endpoints.
• useAuthMutation(authFn, mutationKey, options?) / authMutationOptions(authFn, mutationKey) — write-style endpoints.

Both wire throw: true into fetchOptions so results reject with a BetterFetchError instead of resolving to { error }.

Next