React Hooks

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

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	—	Wait for these queries to re-resolve before un-suspending
waitOnTimeout	number	—	Timeout in milliseconds to resolve the wait lock early

Returns

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

---

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.