Overview

The @better-auth-ui/react package provides hooks for Better Auth UI components. It uses TanStack Query and provides a hook for each supported endpoint.

Each hook wraps useQuery or useMutation and a matching core options factory. Use the hook in a component.

Use a factory from @better-auth-ui/core when TanStack Query requires a queryOptions or mutationOptions object.

Prerequisites

Wrap your app with a QueryClientProvider above <AuthProvider>.

npm install @tanstack/react-query

Cache keys

All keys start with "auth". Queries for one user use the ["auth", "user", userId, ...] prefix.

This structure clears user queries after sign-out or an account switch. Mutation keys are stable for useIsMutating and global MutationCache observers.

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

import { sessionOptions, signInEmailOptions } from "@better-auth-ui/core"

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

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

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

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

Escape hatches

For a Better Auth endpoint without a specific hook, use a generic hook:

• useAuthQuery(authFn, queryKey, options?): read endpoints.
• useAuthMutation(authFn, mutationKey, options?): mutation endpoints.

For loaders and prefetch operations, import authQueryOptions(authFn, queryKey, params?) from @better-auth-ui/core. Mutation endpoints use their core options factory.

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

Next