@better-auth-ui/react 1.6.2 → 1.6.4

package/src/mutations/username/is-username-available-mutation.ts

@@ -0,0 +1,62 @@
+import { authMutationKeys } from "@better-auth-ui/core"
+import { mutationOptions, useMutation } from "@tanstack/react-query"
+import type { BetterFetchError } from "better-auth/react"
+
+import type { UsernameAuthClient } from "../../lib/auth-client"
+
+export type IsUsernameAvailableParams<TAuthClient extends UsernameAuthClient> =
+  Parameters<TAuthClient["isUsernameAvailable"]>[0]
+
+export type IsUsernameAvailableOptions<TAuthClient extends UsernameAuthClient> =
+  Omit<
+    ReturnType<typeof isUsernameAvailableOptions<TAuthClient>>,
+    "mutationKey" | "mutationFn"
+  >
+
+/**
+ * Mutation options factory for checking username availability.
+ *
+ * Modeled as a mutation because callers typically trigger the check on
+ * user action (debounced input, form submit) rather than on mount.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function isUsernameAvailableOptions<
+  TAuthClient extends UsernameAuthClient
+>(authClient: TAuthClient) {
+  const mutationKey = authMutationKeys.isUsernameAvailable
+
+  const mutationFn = (params: IsUsernameAvailableParams<TAuthClient>) =>
+    authClient.isUsernameAvailable({
+      ...params,
+      fetchOptions: { ...params?.fetchOptions, throw: true }
+    })
+
+  return mutationOptions<
+    Awaited<ReturnType<typeof mutationFn>>,
+    BetterFetchError,
+    Parameters<typeof mutationFn>[0]
+  >({
+    mutationKey,
+    mutationFn
+  })
+}
+
+/**
+ * Create a mutation for checking whether a username is available.
+ *
+ * Wraps `authClient.isUsernameAvailable` and forwards React Query mutation
+ * options such as `onSuccess`, `onError`, and `retry`.
+ *
+ * @param authClient - The Better Auth client with the username plugin.
+ * @param options - React Query options forwarded to `useMutation`.
+ */
+export function useIsUsernameAvailable<TAuthClient extends UsernameAuthClient>(
+  authClient: TAuthClient,
+  options?: IsUsernameAvailableOptions<TAuthClient>
+) {
+  return useMutation({
+    ...isUsernameAvailableOptions(authClient),
+    ...options
+  })
+}

package/src/mutations/username/sign-in-username-mutation.ts

@@ -0,0 +1,74 @@
+import { authMutationKeys } from "@better-auth-ui/core"
+import {
+  mutationOptions,
+  useMutation,
+  useQueryClient
+} from "@tanstack/react-query"
+import type { BetterFetchError } from "better-auth/react"
+
+import type { UsernameAuthClient } from "../../lib/auth-client"
+import { sessionOptions } from "../../queries/auth/session-query"
+
+export type SignInUsernameParams<TAuthClient extends UsernameAuthClient> =
+  Parameters<TAuthClient["signIn"]["username"]>[0]
+
+export type SignInUsernameOptions<TAuthClient extends UsernameAuthClient> =
+  Omit<
+    ReturnType<typeof signInUsernameOptions<TAuthClient>>,
+    "mutationKey" | "mutationFn"
+  >
+
+/**
+ * Mutation options factory for username/password sign-in.
+ *
+ * @param authClient - The Better Auth client.
+ */
+export function signInUsernameOptions<TAuthClient extends UsernameAuthClient>(
+  authClient: TAuthClient
+) {
+  const mutationKey = authMutationKeys.signIn.username
+
+  const mutationFn = (params: SignInUsernameParams<TAuthClient>) =>
+    authClient.signIn.username({
+      ...params,
+      fetchOptions: { ...params?.fetchOptions, throw: true }
+    })
+
+  return mutationOptions<
+    Awaited<ReturnType<typeof mutationFn>>,
+    BetterFetchError,
+    Parameters<typeof mutationFn>[0]
+  >({
+    mutationKey,
+    mutationFn
+  })
+}
+
+/**
+ * Create a mutation for username/password sign-in.
+ *
+ * Wraps `authClient.signIn.username`, resets the session query on success so
+ * the new session is refetched, and forwards React Query mutation options
+ * such as `onSuccess`, `onError`, and `retry`.
+ *
+ * @param authClient - The Better Auth client with the username plugin.
+ * @param options - React Query options forwarded to `useMutation`.
+ */
+export function useSignInUsername<TAuthClient extends UsernameAuthClient>(
+  authClient: TAuthClient,
+  options?: SignInUsernameOptions<TAuthClient>
+) {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    ...signInUsernameOptions(authClient),
+    ...options,
+    onSuccess: async (...args) => {
+      queryClient.resetQueries({
+        queryKey: sessionOptions(authClient).queryKey
+      })
+
+      await options?.onSuccess?.(...args)
+    }
+  })
+}

package/src/queries/auth/session-query.ts

@@ -0,0 +1,135 @@
+import { authQueryKeys } from "@better-auth-ui/core"
+import {
+  type DataTag,
+  type QueryClient,
+  queryOptions,
+  useQuery
+} from "@tanstack/react-query"
+import type { BetterFetchError } from "better-auth/react"
+
+import type { AuthClient, InferData } from "../../lib/auth-client"
+
+export type SessionData<TAuthClient extends AuthClient = AuthClient> =
+  InferData<TAuthClient["getSession"]>
+
+export type Session<TAuthClient extends AuthClient = AuthClient> = NonNullable<
+  SessionData<TAuthClient>
+>
+
+export type SessionParams<TAuthClient extends AuthClient> = Parameters<
+  TAuthClient["getSession"]
+>[0]
+
+export type SessionOptions<TAuthClient extends AuthClient> = Omit<
+  ReturnType<typeof sessionOptions<TAuthClient>>,
+  "queryKey" | "queryFn"
+>
+
+/**
+ * Query options factory for the current session.
+ *
+ * Shares a query key with the server-side `sessionOptions` so that data
+ * prefetched during SSR hydrates seamlessly into the client cache.
+ *
+ * @param authClient - The Better Auth client.
+ * @param params - Parameters forwarded to `authClient.getSession`.
+ */
+export function sessionOptions<TAuthClient extends AuthClient>(
+  authClient: TAuthClient,
+  params?: SessionParams<TAuthClient>
+) {
+  type TData = SessionData<TAuthClient>
+  const queryKey = authQueryKeys.session
+
+  const options = queryOptions<TData, BetterFetchError, TData, typeof queryKey>(
+    {
+      queryKey,
+      queryFn: ({ signal }) =>
+        authClient.getSession({
+          ...params,
+          fetchOptions: { ...params?.fetchOptions, signal, throw: true }
+        }) as Promise<TData>
+    }
+  )
+
+  return options as typeof options & {
+    queryKey: DataTag<typeof queryKey, TData, BetterFetchError>
+  }
+}
+
+/**
+ * Get the current session from the query cache, calling `fetchSession` under
+ * the hood if no cached entry exists. Resolves with the session data, making
+ * it ideal for loaders or `beforeLoad` guards.
+ *
+ * @param queryClient - The React Query client.
+ * @param authClient - The Better Auth client.
+ * @param params - Parameters forwarded to `authClient.getSession`.
+ */
+export const ensureSession = <TAuthClient extends AuthClient>(
+  queryClient: QueryClient,
+  authClient: TAuthClient,
+  params?: SessionParams<TAuthClient>
+) => queryClient.ensureQueryData(sessionOptions(authClient, params))
+
+/**
+ * Prefetch the current session into the query cache. Behaves like
+ * `fetchSession`, but does not throw on error and does not return the data —
+ * use this to warm the cache without blocking navigation.
+ *
+ * @param queryClient - The React Query client.
+ * @param authClient - The Better Auth client.
+ * @param params - Parameters forwarded to `authClient.getSession`.
+ */
+export const prefetchSession = <TAuthClient extends AuthClient>(
+  queryClient: QueryClient,
+  authClient: TAuthClient,
+  params?: SessionParams<TAuthClient>
+) => queryClient.prefetchQuery(sessionOptions(authClient, params))
+
+/**
+ * Fetch and cache the current session, resolving with the data or throwing
+ * on error. If a cached entry exists and is neither invalidated nor older
+ * than `staleTime`, the cached value is returned without a network call;
+ * otherwise the latest data is fetched.
+ *
+ * @param queryClient - The React Query client.
+ * @param authClient - The Better Auth client.
+ * @param params - Parameters forwarded to `authClient.getSession`.
+ */
+export const fetchSession = <TAuthClient extends AuthClient>(
+  queryClient: QueryClient,
+  authClient: TAuthClient,
+  params?: SessionParams<TAuthClient>
+) => queryClient.fetchQuery(sessionOptions(authClient, params))
+
+export type UseSessionOptions<TAuthClient extends AuthClient> =
+  SessionOptions<TAuthClient> & SessionParams<TAuthClient>
+
+/**
+ * Subscribe to the current session via TanStack Query.
+ *
+ * Shares a query key with the server-side `sessionOptions`, so SSR-hydrated
+ * session data is reused from the cache without an immediate refetch.
+ *
+ * @param authClient - The Better Auth client.
+ * @param options - `getSession` params (`query`, `fetchOptions`) merged
+ *   with `useQuery` options (e.g. `enabled`, `staleTime`, `select`).
+ * @param queryClient - Optional custom `QueryClient`. Defaults to the client
+ *   from the nearest `QueryClientProvider`.
+ */
+export function useSession<TAuthClient extends AuthClient>(
+  authClient: TAuthClient,
+  options: UseSessionOptions<TAuthClient> = {},
+  queryClient?: QueryClient
+) {
+  const { query, fetchOptions, ...queryOptions } = options
+
+  return useQuery(
+    {
+      ...sessionOptions(authClient, { query, fetchOptions }),
+      ...queryOptions
+    },
+    queryClient
+  )
+}

package/src/queries/auth-query-options.ts

@@ -0,0 +1,83 @@
+import {
+  type DataTag,
+  type QueryKey,
+  queryOptions,
+  type UseQueryOptions
+} from "@tanstack/react-query"
+import type { BetterFetchError, BetterFetchOption } from "better-auth/client"
+
+/**
+ * Read-style Better Auth client method (params shape `{ query?, fetchOptions? }`).
+ * Mutation-style endpoints use `AuthMutationFn` / `useAuthMutation` instead.
+ */
+export type AuthQueryFn<TData = unknown> = (params: {
+  query?: Record<string, unknown>
+  fetchOptions?: BetterFetchOption
+}) => Promise<{ data: TData }>
+
+export type AuthQueryFnData<TFn> =
+  TFn extends AuthQueryFn<infer TData> ? TData : never
+
+/**
+ * Final query key produced by {@link authQueryOptions}: the caller's prefix
+ * followed by `params.query ?? null`.
+ */
+export type AuthQueryKey<
+  TFn extends AuthQueryFn = AuthQueryFn,
+  TPrefix extends QueryKey = QueryKey
+> = readonly [...TPrefix, NonNullable<Parameters<TFn>[0]>["query"] | null]
+
+/**
+ * Return type of {@link authQueryOptions}. Named so TypeScript emits
+ * `DataTag<…>` by reference in the `.d.ts`, instead of the raw
+ * `{ [dataTagSymbol]: … }` intersection — which triggers a declaration-emit
+ * bug where `dataTagSymbol` isn't re-imported at the use site and silently
+ * breaks `setQueryData`/`getQueryData` type inference at the consumer.
+ */
+export type AuthQueryOptions<
+  TFn extends AuthQueryFn = AuthQueryFn,
+  TPrefix extends QueryKey = QueryKey
+> = Omit<
+  UseQueryOptions<
+    AuthQueryFnData<TFn>,
+    BetterFetchError,
+    AuthQueryFnData<TFn>,
+    AuthQueryKey<TFn, TPrefix>
+  >,
+  "queryKey"
+> & {
+  queryKey: DataTag<
+    AuthQueryKey<TFn, TPrefix>,
+    AuthQueryFnData<TFn>,
+    BetterFetchError
+  >
+}
+
+/**
+ * Build `queryOptions` for a Better Auth endpoint.
+ *
+ * Injects React Query's `signal` and `throw: true` into `fetchOptions` so the
+ * request is cancelled on unmount and errors surface as `BetterFetchError`
+ * instead of `{ data, error }`.
+ *
+ * @param authFn - Better Auth client method (e.g. `authClient.getSession`).
+ * @param queryKey - Scope prefix for the key. `params.query` is appended automatically.
+ * @param params - Parameters forwarded to `authFn`.
+ */
+export function authQueryOptions<
+  TFn extends AuthQueryFn,
+  const TPrefix extends QueryKey
+>(
+  authFn: TFn,
+  queryKey: TPrefix,
+  params?: Parameters<TFn>[0]
+): AuthQueryOptions<TFn, TPrefix> {
+  return queryOptions<AuthQueryFnData<TFn>, BetterFetchError>({
+    queryKey: [...queryKey, params?.query ?? null] as const,
+    queryFn: ({ signal }) =>
+      authFn({
+        ...params,
+        fetchOptions: { ...params?.fetchOptions, signal, throw: true }
+      }) as Promise<AuthQueryFnData<TFn>>
+  }) as AuthQueryOptions<TFn, TPrefix>
+}

package/src/queries/multi-session/list-device-sessions-query.ts

@@ -0,0 +1,177 @@
+import { authQueryKeys } from "@better-auth-ui/core"
+import {
+  type DataTag,
+  type QueryClient,
+  queryOptions,
+  skipToken,
+  useQuery
+} from "@tanstack/react-query"
+import type { BetterFetchError } from "better-auth/react"
+
+import type { InferData, MultiSessionAuthClient } from "../../lib/auth-client"
+import { useSession } from "../auth/session-query"
+
+export type ListDeviceSessionsData<
+  TAuthClient extends MultiSessionAuthClient = MultiSessionAuthClient
+> = InferData<TAuthClient["multiSession"]["listDeviceSessions"]>
+
+export type ListDeviceSession<
+  TAuthClient extends MultiSessionAuthClient = MultiSessionAuthClient
+> = NonNullable<ListDeviceSessionsData<TAuthClient>>[number]
+
+export type ListDeviceSessionsParams<
+  TAuthClient extends MultiSessionAuthClient
+> = Parameters<TAuthClient["multiSession"]["listDeviceSessions"]>[0]
+
+export type ListDeviceSessionsOptions<
+  TAuthClient extends MultiSessionAuthClient
+> = Omit<
+  ReturnType<typeof listDeviceSessionsOptions<TAuthClient>>,
+  "queryKey" | "queryFn"
+>
+
+/**
+ * Query options factory for the current user's device sessions.
+ *
+ * @param authClient - The Better Auth client with the multi-session plugin.
+ * @param userId - The current signed-in user's ID. Used for cache partitioning.
+ * @param params - Parameters forwarded to `authClient.multiSession.listDeviceSessions`.
+ */
+export function listDeviceSessionsOptions<
+  TAuthClient extends MultiSessionAuthClient
+>(
+  authClient: TAuthClient,
+  userId: string | undefined,
+  params?: ListDeviceSessionsParams<TAuthClient>
+) {
+  type TData = ListDeviceSessionsData<TAuthClient>
+  const queryKey = authQueryKeys.listDeviceSessions(userId, params?.query)
+
+  const options = queryOptions<TData, BetterFetchError, TData, typeof queryKey>(
+    {
+      queryKey,
+      queryFn: ({ signal }) =>
+        authClient.multiSession.listDeviceSessions({
+          ...params,
+          fetchOptions: { ...params?.fetchOptions, signal, throw: true }
+        }) as Promise<TData>
+    }
+  )
+
+  return options as typeof options & {
+    queryKey: DataTag<typeof queryKey, TData, BetterFetchError>
+  }
+}
+
+/**
+ * Get the current user's device sessions from the query cache, calling
+ * `fetchListDeviceSessions` under the hood if no cached entry exists.
+ * Resolves with the device session list, making it ideal for loaders or
+ * `beforeLoad` guards.
+ *
+ * @param queryClient - The React Query client.
+ * @param authClient - The Better Auth client with the multi-session plugin.
+ * @param userId - The signed-in user's ID, used for cache partitioning.
+ * @param params - Parameters forwarded to `authClient.multiSession.listDeviceSessions`.
+ */
+export const ensureListDeviceSessions = <
+  TAuthClient extends MultiSessionAuthClient
+>(
+  queryClient: QueryClient,
+  authClient: TAuthClient,
+  userId: string,
+  params?: ListDeviceSessionsParams<TAuthClient>
+) =>
+  queryClient.ensureQueryData(
+    listDeviceSessionsOptions(authClient, userId, params)
+  )
+
+/**
+ * Prefetch the current user's device sessions into the query cache. Behaves
+ * like `fetchListDeviceSessions`, but does not throw on error and does not
+ * return the data — use this to warm the cache without blocking navigation.
+ *
+ * @param queryClient - The React Query client.
+ * @param authClient - The Better Auth client with the multi-session plugin.
+ * @param userId - The signed-in user's ID, used for cache partitioning.
+ * @param params - Parameters forwarded to `authClient.multiSession.listDeviceSessions`.
+ */
+export const prefetchListDeviceSessions = <
+  TAuthClient extends MultiSessionAuthClient
+>(
+  queryClient: QueryClient,
+  authClient: TAuthClient,
+  userId: string,
+  params?: ListDeviceSessionsParams<TAuthClient>
+) =>
+  queryClient.prefetchQuery(
+    listDeviceSessionsOptions(authClient, userId, params)
+  )
+
+/**
+ * Fetch and cache the current user's device sessions, resolving with the
+ * data or throwing on error. If a cached entry exists and is neither
+ * invalidated nor older than `staleTime`, the cached value is returned
+ * without a network call; otherwise the latest data is fetched.
+ *
+ * @param queryClient - The React Query client.
+ * @param authClient - The Better Auth client with the multi-session plugin.
+ * @param userId - The signed-in user's ID, used for cache partitioning.
+ * @param params - Parameters forwarded to `authClient.multiSession.listDeviceSessions`.
+ */
+export const fetchListDeviceSessions = <
+  TAuthClient extends MultiSessionAuthClient
+>(
+  queryClient: QueryClient,
+  authClient: TAuthClient,
+  userId: string,
+  params?: ListDeviceSessionsParams<TAuthClient>
+) =>
+  queryClient.fetchQuery(listDeviceSessionsOptions(authClient, userId, params))
+
+export type UseListDeviceSessionsOptions<
+  TAuthClient extends MultiSessionAuthClient
+> = ListDeviceSessionsOptions<TAuthClient> &
+  ListDeviceSessionsParams<TAuthClient>
+
+/**
+ * Subscribe to the current user's device sessions (multi-session account
+ * switcher) via TanStack Query.
+ *
+ * Shares a query key with the server-side `listDeviceSessionsOptions`, so
+ * SSR-hydrated data is reused from the cache without an immediate refetch.
+ * The query is gated on a signed-in user; while the session is loading or
+ * absent, the underlying `queryFn` is replaced with `skipToken`.
+ *
+ * @param authClient - The Better Auth client with the multi-session plugin.
+ * @param options - `listDeviceSessions` params (`query`, `fetchOptions`)
+ *   merged with `useQuery` options (e.g. `enabled`, `staleTime`, `select`).
+ * @param queryClient - Optional custom `QueryClient`. Defaults to the client
+ *   from the nearest `QueryClientProvider`.
+ */
+export function useListDeviceSessions<
+  TAuthClient extends MultiSessionAuthClient
+>(
+  authClient: TAuthClient,
+  options: UseListDeviceSessionsOptions<TAuthClient> = {},
+  queryClient?: QueryClient
+) {
+  const { data: session } = useSession(authClient, undefined, queryClient)
+  const userId = session?.user.id
+
+  const { query, fetchOptions, ...queryOptions } = options
+
+  const baseOptions = listDeviceSessionsOptions(authClient, userId, {
+    query,
+    fetchOptions
+  })
+
+  return useQuery(
+    {
+      ...queryOptions,
+      ...baseOptions,
+      queryFn: userId ? baseOptions.queryFn : skipToken
+    },
+    queryClient
+  )
+}

package/src/queries/passkey/list-passkeys-query.ts

@@ -0,0 +1,154 @@
+import { authQueryKeys } from "@better-auth-ui/core"
+import {
+  type DataTag,
+  type QueryClient,
+  queryOptions,
+  skipToken,
+  useQuery
+} from "@tanstack/react-query"
+import type { BetterFetchError } from "better-auth/react"
+
+import type { InferData, PasskeyAuthClient } from "../../lib/auth-client"
+import { useSession } from "../auth/session-query"
+
+export type ListPasskeysData<TAuthClient extends PasskeyAuthClient> = InferData<
+  TAuthClient["passkey"]["listUserPasskeys"]
+>
+
+export type ListPasskeysParams<TAuthClient extends PasskeyAuthClient> =
+  Parameters<TAuthClient["passkey"]["listUserPasskeys"]>[0]
+
+export type ListPasskey<
+  TAuthClient extends PasskeyAuthClient = PasskeyAuthClient
+> = NonNullable<ListPasskeysData<TAuthClient>>[number]
+
+export type ListPasskeysOptions<TAuthClient extends PasskeyAuthClient> = Omit<
+  ReturnType<typeof listPasskeysOptions<TAuthClient>>,
+  "queryKey" | "queryFn"
+>
+
+/**
+ * Query options factory for the current user's passkeys.
+ *
+ * @param authClient - The Better Auth client with the passkey plugin.
+ * @param userId - The current signed-in user's ID. Used for cache partitioning.
+ * @param params - Parameters forwarded to `authClient.passkey.listUserPasskeys`.
+ */
+export function listPasskeysOptions<TAuthClient extends PasskeyAuthClient>(
+  authClient: TAuthClient,
+  userId: string | undefined,
+  params?: ListPasskeysParams<TAuthClient>
+) {
+  type TData = ListPasskeysData<TAuthClient>
+  const queryKey = authQueryKeys.listPasskeys(userId, params?.query)
+
+  const options = queryOptions<TData, BetterFetchError, TData, typeof queryKey>(
+    {
+      queryKey,
+      queryFn: ({ signal }) =>
+        authClient.passkey.listUserPasskeys({
+          ...params,
+          fetchOptions: { ...params?.fetchOptions, signal, throw: true }
+        }) as Promise<TData>
+    }
+  )
+
+  return options as typeof options & {
+    queryKey: DataTag<typeof queryKey, TData, BetterFetchError>
+  }
+}
+
+/**
+ * Get the current user's passkeys from the query cache, calling
+ * `fetchListPasskeys` under the hood if no cached entry exists. Resolves
+ * with the passkey list, making it ideal for loaders or `beforeLoad` guards.
+ *
+ * @param queryClient - The React Query client.
+ * @param authClient - The Better Auth client with the passkey plugin.
+ * @param userId - The signed-in user's ID, used for cache partitioning.
+ * @param params - Parameters forwarded to `authClient.passkey.listUserPasskeys`.
+ */
+export const ensureListPasskeys = <TAuthClient extends PasskeyAuthClient>(
+  queryClient: QueryClient,
+  authClient: TAuthClient,
+  userId: string,
+  params?: ListPasskeysParams<TAuthClient>
+) =>
+  queryClient.ensureQueryData(listPasskeysOptions(authClient, userId, params))
+
+/**
+ * Prefetch the current user's passkeys into the query cache. Behaves like
+ * `fetchListPasskeys`, but does not throw on error and does not return
+ * the data — use this to warm the cache without blocking navigation.
+ *
+ * @param queryClient - The React Query client.
+ * @param authClient - The Better Auth client with the passkey plugin.
+ * @param userId - The signed-in user's ID, used for cache partitioning.
+ * @param params - Parameters forwarded to `authClient.passkey.listUserPasskeys`.
+ */
+export const prefetchListPasskeys = <TAuthClient extends PasskeyAuthClient>(
+  queryClient: QueryClient,
+  authClient: TAuthClient,
+  userId: string,
+  params?: ListPasskeysParams<TAuthClient>
+) => queryClient.prefetchQuery(listPasskeysOptions(authClient, userId, params))
+
+/**
+ * Fetch and cache the current user's passkeys, resolving with the data or
+ * throwing on error. If a cached entry exists and is neither invalidated
+ * nor older than `staleTime`, the cached value is returned without a
+ * network call; otherwise the latest data is fetched.
+ *
+ * @param queryClient - The React Query client.
+ * @param authClient - The Better Auth client with the passkey plugin.
+ * @param userId - The signed-in user's ID, used for cache partitioning.
+ * @param params - Parameters forwarded to `authClient.passkey.listUserPasskeys`.
+ */
+export const fetchListPasskeys = <TAuthClient extends PasskeyAuthClient>(
+  queryClient: QueryClient,
+  authClient: TAuthClient,
+  userId: string,
+  params?: ListPasskeysParams<TAuthClient>
+) => queryClient.fetchQuery(listPasskeysOptions(authClient, userId, params))
+
+export type UseListPasskeysOptions<TAuthClient extends PasskeyAuthClient> =
+  ListPasskeysOptions<TAuthClient> & ListPasskeysParams<TAuthClient>
+
+/**
+ * Subscribe to the current user's passkeys via TanStack Query.
+ *
+ * Shares a query key with the server-side `listPasskeysOptions`, so
+ * SSR-hydrated data is reused from the cache without an immediate refetch.
+ * The query is gated on a signed-in user; while the session is loading or
+ * absent, the underlying `queryFn` is replaced with `skipToken`.
+ *
+ * @param authClient - The Better Auth client with the passkey plugin.
+ * @param options - `listPasskeys` params (`query`, `fetchOptions`) merged
+ *   with `useQuery` options (e.g. `enabled`, `staleTime`, `select`).
+ * @param queryClient - Optional custom `QueryClient`. Defaults to the client
+ *   from the nearest `QueryClientProvider`.
+ */
+export function useListPasskeys<TAuthClient extends PasskeyAuthClient>(
+  authClient: TAuthClient,
+  options: UseListPasskeysOptions<TAuthClient> = {},
+  queryClient?: QueryClient
+) {
+  const { data: session } = useSession(authClient, undefined, queryClient)
+  const userId = session?.user.id
+
+  const { query, fetchOptions, ...queryOptions } = options
+
+  const baseOptions = listPasskeysOptions(authClient, userId, {
+    query,
+    fetchOptions
+  })
+
+  return useQuery(
+    {
+      ...queryOptions,
+      ...baseOptions,
+      queryFn: userId ? baseOptions.queryFn : skipToken
+    },
+    queryClient
+  )
+}