kitten.sh
1---
2title: urql (React)
3order: 1
4---
5
6# React API
7
8> **Note:** These API docs are deprecated as we now keep TSDocs in all published packages.
9> You can view TSDocs while using these packages in your editor, as long as it supports the
10> TypeScript Language Server.
11> We're planning to replace these API docs with a separate web app soon.
12
13## useQuery
14
15Accepts a single required options object as an input with the following properties:
16
17| Prop | Type | Description |
18| --------------- | ------------------------ | -------------------------------------------------------------------------------------------------------- |
19| `query` | `string \| DocumentNode` | The query to be executed. Accepts as a plain string query or GraphQL DocumentNode. |
20| `variables` | `?object` | The variables to be used with the GraphQL request. |
21| `requestPolicy` | `?RequestPolicy` | An optional [request policy](./core.md#requestpolicy) that should be used specifying the cache strategy. |
22| `pause` | `?boolean` | A boolean flag instructing [execution to be paused](../basics/react-preact.md#pausing-usequery). |
23| `context` | `?object` | Holds the contextual information for the query. |
24
25This hook returns a tuple of the shape `[result, executeQuery]`.
26
27- The `result` is an object with the shape of an [`OperationResult`](./core.md#operationresult) with
28 an added `fetching: boolean` property, indicating whether the query is being fetched.
29- The `executeQuery` function optionally accepts
30 [`Partial<OperationContext>`](./core.md#operationcontext) and reexecutes the current query when
31 it's called. When `pause` is set to `true` this executes the query, overriding the otherwise
32 paused hook.
33
34[Read more about how to use the `useQuery` API on the "Queries" page.](../basics/react-preact.md#queries)
35
36## useMutation
37
38Accepts a single `query` argument of type `string | DocumentNode` and returns a tuple of the shape
39`[result, executeMutation]`.
40
41- The `result` is an object with the shape of an [`OperationResult`](./core.md#operationresult) with
42 an added `fetching: boolean` property, indicating whether the mutation is being executed.
43- The `executeMutation` function accepts variables and optionally
44 [`Partial<OperationContext>`](./core.md#operationcontext) and may be used to start executing a
45 mutation. It returns a `Promise` resolving to an [`OperationResult`](./core.md#operationresult).
46
47[Read more about how to use the `useMutation` API on the "Mutations"
48page.](../basics/react-preact.md#mutations)
49
50## useSubscription
51
52Accepts a single required options object as an input with the following properties:
53
54| Prop | Type | Description |
55| ----------- | ------------------------ | ------------------------------------------------------------------------------------------------ |
56| `query` | `string \| DocumentNode` | The query to be executed. Accepts as a plain string query or GraphQL DocumentNode. |
57| `variables` | `?object` | The variables to be used with the GraphQL request. |
58| `pause` | `?boolean` | A boolean flag instructing [execution to be paused](../basics/react-preact.md#pausing-usequery). |
59| `context` | `?object` | Holds the contextual information for the query. |
60
61The hook optionally accepts a second argument, which may be a handler function with a type signature
62of:
63
64```js
65type SubscriptionHandler<T, R> = (previousData: R | undefined, data: T) => R;
66```
67
68This function will be called with the previous data (or `undefined`) and the new data that's
69incoming from a subscription event, and may be used to "reduce" the data over time, altering the
70value of `result.data`.
71
72This hook returns a tuple of the shape `[result, executeSubscription]`.
73
74- The `result` is an object with the shape of an [`OperationResult`](./core.md#operationresult).
75- The `executeSubscription` function optionally accepts
76 [`Partial<OperationContext>`](./core.md#operationcontext) and restarts the current subscription when
77 it's called. When `pause` is set to `true` this starts the subscription, overriding the otherwise
78 paused hook.
79
80The `fetching: boolean` property on the `result` may change to `false` when the server proactively
81ends the subscription. By default, `urql` is unable able to start subscriptions, since this requires
82some additional setup.
83
84[Read more about how to use the `useSubscription` API on the "Subscriptions"
85page.](../advanced/subscriptions.md)
86
87## Query Component
88
89This component is a wrapper around [`useQuery`](#usequery), exposing a [render prop
90API](https://reactjs.org/docs/render-props.html) for cases where hooks aren't desirable.
91
92The API of the `Query` component mirrors the API of [`useQuery`](#usequery). The props that `<Query>`
93accepts are the same as `useQuery`'s options object.
94
95A function callback must be passed to `children` that receives the query result and must return a
96React element. The second argument of the hook's tuple, `executeQuery` is passed as an added property
97on the query result.
98
99## Mutation Component
100
101This component is a wrapper around [`useMutation`](#usemutation), exposing a [render prop
102API](https://reactjs.org/docs/render-props.html) for cases where hooks aren't desirable.
103
104The `Mutation` component accepts a `query` prop, and a function callback must be passed to `children`
105that receives the mutation result and must return a React element. The second argument of
106`useMutation`'s returned tuple, `executeMutation` is passed as an added property on the mutation
107result object.
108
109## Subscription Component
110
111This component is a wrapper around [`useSubscription`](#usesubscription), exposing a [render prop
112API](https://reactjs.org/docs/render-props.html) for cases where hooks aren't desirable.
113
114The API of the `Subscription` component mirrors the API of [`useSubscription`](#usesubscription).
115The props that `<Mutation>` accepts are the same as `useSubscription`'s options object, with an
116added, optional `handler` prop that may be passed, which for the `useSubscription` hook is instead
117the second argument.
118
119A function callback must be passed to `children` that receives the subscription result and must
120return a React element. The second argument of the hook's tuple, `executeSubscription` is passed as
121an added property on the subscription result.
122
123## Context
124
125`urql` is used in React by adding a provider around where the [`Client`](./core.md#client) is
126supposed to be used. Internally this means that `urql` creates a
127[React Context](https://reactjs.org/docs/context.html).
128
129All created parts of this context are exported by `urql`, namely:
130
131- `Context`
132- `Provider`
133- `Consumer`
134
135To keep examples brief, `urql` creates a default client with the `url` set to `'/graphql'`. This
136client will be used when no `Provider` wraps any of `urql`'s hooks. However, to prevent this default
137client from being used accidentally, a warning is output in the console for the default client.
138
139### useClient
140
141`urql` also exports a `useClient` hook, which is a convenience wrapper like the following:
142
143```js
144import React from 'react';
145import { Context } from 'urql';
146
147const useClient = () => React.useContext(Context);
148```
149
150However, this hook is also responsible for outputting the default client warning that's mentioned
151above, and should thus be preferred over manually using `useContext` with `urql`'s `Context`.