API Reference

Composables

API reference for client-side composables.

useUserSession

The primary composable for accessing authentication state. Returns reactive user, session, and auth client.

pages/login.vue

const { loggedIn, user, session, client, signIn, signOut } = useUserSession()

loggedIn

ComputedRef<boolean>

true if the user is currently authenticated.

user

Ref<AuthUser | null>

The current user object, inferred from your config.

session

Ref<AuthSession | null>

The current session object.

ready

Ref<boolean>

true when the initial session fetch is complete.

client

AuthClient | null

Direct access to the Better Auth client instance.

Methods

Proxies Better Auth signIn.

await signIn.email({
  email: 'user@example.com',
  password: 'password'
})

Promise Behavior

Methods like signIn return a promise that resolves when the server responds, not when local state updates.

// This awaits the server response
await client.signIn.email({ email, password })

// Local state updates asynchronously after
// Use onSuccess callback for actions that depend on updated state
await client.signIn.email(
  { email, password },
  { onSuccess: () => navigateTo('/dashboard') }
)

Proxies Better Auth signUp with the same onSuccess behavior as signIn.

await signUp.email({
  email: 'user@example.com',
  password: 'password'
})

`signOut`

Signs the user out and clears the local session state.

await signOut()

Options

await signOut({
  onSuccess: () => navigateTo('/'),
})

`waitForSession()`

Waits for session state to be ready. Resolves when user is logged in or after 5 second timeout.

await waitForSession()
// Session is now ready (or timed out)

Use this when you need to ensure session state before proceeding. The function always resolves - it doesn't throw or return a value.

`fetchSession`

Manually triggers a session refresh. Useful if you've updated user data on the server via a side channel.

await fetchSession()

Options

await fetchSession({
  headers, // optional HeadersInit
  force: true, // disables Better Auth cookie cache for this fetch
})

`updateUser`

Optimistically updates the local user object.

updateUser({ name: 'New Name' })

Reactivity: user and session are global states using useState. Changes in one component are instantly reflected everywhere.