React Hooks

All exports are available from @requence/socketql/client/react.

createClient

React-aware variant of the base createClient. Live query push updates are automatically wrapped in React’s startTransition, so they are treated as transition updates instead of urgent ones.

This prevents live query pushes from triggering a Suspense fallback while a useTransition is pending — for example, during a branch switch where downstream components may suspend to load new data.

import { createClient } from '@requence/socketql/client/react'

const client = createClient({
  auth: () => ({ branch: localStorage.getItem('branch') }),
})

The function accepts all the same options as the base createClient. Internally it passes startTransition as the wrapLiveQueryUpdate option.

Tip

Use this instead of importing from @requence/socketql/client when your app uses React Suspense boundaries and transitions.

---

SocketQLProvider

Wraps URQL’s Provider and manages the WebSocket connection lifecycle. Calls connect() on mount. By default, connection errors are thrown to the nearest React error boundary. Pass onConnectError to handle them manually instead.

import { SocketQLProvider } from '@requence/socketql/client/react'

<SocketQLProvider client={client}>
  <App />
</SocketQLProvider>

Props

Prop	Type	Description
client	SocketQLClient	The client returned by createClient
onConnect	() => void	Called on successful connection
onConnectError	(error: ConnectionError) => void	Called on connection error. When set, errors are not thrown to the error boundary.

Error Boundary Integration

When no onConnectError prop is provided, the provider throws the ConnectionError during render. Wrap it in an error boundary to handle rejections:

<ErrorBoundary fallback={<LoginPage />}>
  <SocketQLProvider client={client}>
    <App />
  </SocketQLProvider>
</ErrorBoundary>

The same client can be reused after the error boundary resets — the provider will re-register its listeners and call connect() again.

Manual Error Handling

Pass onConnectError to handle connection errors without an error boundary. This is useful when you want to call client.reconnect() after updating auth state:

<SocketQLProvider
  client={client}
  onConnectError={(err) => {
    console.log(err.data) // e.g. { code: 'EXPIRED' }
    refreshToken().then(() => client.reconnect())
  }}
>
  <App />
</SocketQLProvider>

SocketQLClient

import type { SocketQLClient } from '@requence/socketql/client/react'

---

useQuery

Suspense-ready query hook. Throws on errors (use with an error boundary).

function useQuery<Data, Variables>(
  args: UseQueryArgs<Variables, Data>
): readonly [Data, reexecuteFn]

Parameters

Accepts all URQL UseQueryArgs options:

Option	Type	Description
query	DocumentInput	The GraphQL query document
variables	Variables	Query variables
requestPolicy	string	URQL request policy
pause	boolean	Pause the query

Returns

Returns a tuple of [data, reexecute]. data is the query result, and reexecute is a function to trigger a query execution. Throws the URQL error if the query fails.

---

useMutation

Suspense-aware mutation hook with cache invalidation support.

function useMutation<Data, Variables>(
  args: UseMutationArgs<Data, Variables>
): readonly [OperationResult, executeFn]

Parameters

Option	Type	Default	Description
query	DocumentInput	—	The mutation document
invalidate	string | DocumentNode | Array	—	Queries to invalidate on success
suspense	boolean	true	Whether to trigger Suspense during execution
waitOn	string | DocumentNode | Array | Function	—	Wait for a query/subscription to emit, or resolve when a predicate returns true
waitOnTimeout	number	—	Timeout in milliseconds to resolve the wait lock early

Returns

A tuple of [result, execute], same as URQL’s useMutation.

Waiting on queries or subscriptions

waitOn accepts a query/subscription name (string), a DocumentNode, or an array of names/documents. The mutation’s Suspense lock is held until one result for each specified operation flows through the exchange pipeline — which works for both queries and subscriptions, since all results pass through the same exchange chain.

// Wait for a live query to re-emit after invalidation
const [, executeCreate] = useMutation({
  query: CREATE_USER_MUTATION,
  invalidate: 'Users',
  waitOn: 'Users',
})

// Wait for a subscription event (e.g. list updated via subscription)
const [, executeDuplicate] = useMutation({
  query: DUPLICATE_ITEM_MUTATION,
  waitOn: ITEM_CHANGES_SUBSCRIPTION,
  waitOnTimeout: 3000,
})

Waiting with a predicate

For fine-grained control — such as waiting for a subscription event that matches an ID returned by the mutation — pass a predicate function. It receives the mutation result as its first argument, followed by each incoming OperationResult and the pre-computed operation name. It resolves as soon as it returns true.

// waitOn type when a function:
// (
//   mutationResult: OperationResult<Data, Variables>,
//   result: OperationResult,
//   operationName: string | undefined,
// ) => boolean

const [, executeCreate] = useMutation({
  query: CREATE_ITEM_MUTATION,
  waitOn: (mutationResult, result, name) =>
    name === 'ItemCreated' &&
    result.data?.itemCreated?.id === mutationResult.data?.createItem?.id,
  waitOnTimeout: 5000,
})

Note

The listener is registered before execute() is called and buffers any results that arrive while the mutation is in-flight. Once the mutation response is received, the buffer is flushed against the predicate — then evaluation continues in real-time for every subsequent result. The predicate may therefore be called multiple times until it returns true; keep it a pure expression with no side effects. Use waitOnTimeout as a safety valve in case the expected event never arrives.

---

useSubscription

Thin wrapper around URQL’s useSubscription. Throws on errors (use with an error boundary).

function useSubscription<Data, Result, Variables>(
  args: UseSubscriptionArgs<Variables, Data>,
  handler?: SubscriptionHandler<Data, Result>
): readonly [Result | undefined, executeFn]

Parameters

Option	Type	Description
args	UseSubscriptionArgs<Variables, Data>	URQL subscription arguments
handler	SubscriptionHandler<Data, Result>	Optional handler to accumulate data across events

args accepts all URQL UseSubscriptionArgs options:

Option	Type	Description
query	DocumentInput	The GraphQL subscription document
variables	Variables	Subscription variables
pause	boolean	Pause the subscription

Returns

A tuple of [data, execute]. data is the latest subscription result (or the accumulated result when using a handler). Throws the URQL error if the subscription encounters an error.