kitten.sh
1---
2title: '@urql/vue'
3order: 3
4---
5
6# Vue 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/vue.md#pausing-usequery). |
23| `context` | `?object` | Holds the contextual information for the query. |
24
25Each of these inputs may also be [reactive](https://v3.vuejs.org/api/refs-api.html) (e.g. a `ref`)
26and are allowed to change over time which will issue a new query.
27
28This function returns an object with the shape of an [`OperationResult`](./core.md#operationresult)
29with an added `fetching` property, indicating whether the query is currently being fetched and an
30`isPaused` property which will indicate whether `useQuery` is currently paused and won't
31automatically start querying.
32
33All of the properties on this result object are also marked as
34[reactive](https://v3.vuejs.org/api/refs-api.html) using `ref` and will update accordingly as the
35query is executed.
36
37The result furthermore carries several utility methods:
38
39| Method | Description |
40| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
41| `pause()` | This will pause automatic querying, which is equivalent to setting `pause.value = true` |
42| `resume()` | This will resume a paused automatic querying, which is equivalent to setting `pause.value = false` |
43| `executeQuery(opts)` | This will execute a new query with the given partial [`Partial<OperationContext>`](./core.md#operationcontext) regardless of whether the query is currently paused or not. This also returns the result object again for chaining. |
44
45Furthermore the returned result object of `useQuery` is also a `PromiseLike`, which allows you to
46take advantage of [Vue 3's experimental Suspense feature.](https://vuedose.tips/go-async-in-vue-3-with-suspense/)
47When the promise is used, e.g. you `await useQuery(...)` then the `PromiseLike` will only resolve
48once a result from the API is available.
49
50[Read more about how to use the `useQuery` API on the "Queries" page.](../basics/vue.md#queries)
51
52## useMutation
53
54Accepts a single `query` argument of type `string | DocumentNode` and returns a result object with
55the shape of an [`OperationResult`](./core.md#operationresult) with an added `fetching` property.
56
57All of the properties on this result object are also marked as
58[reactive](https://v3.vuejs.org/api/refs-api.html) using `ref` and will update accordingly as the
59mutation is executed.
60
61The object also carries a special `executeMutation` method, which accepts variables and optionally a
62[`Partial<OperationContext>`](./core.md#operationcontext) and may be used to start executing a
63mutation. It returns a `Promise` resolving to an [`OperationResult`](./core.md#operationresult)
64
65[Read more about how to use the `useMutation` API on the "Mutations"
66page.](../basics/vue.md#mutations)
67
68## useSubscription
69
70Accepts a single required options object as an input with the following properties:
71
72| Prop | Type | Description |
73| ----------- | ------------------------ | --------------------------------------------------------------------------------------- |
74| `query` | `string \| DocumentNode` | The query to be executed. Accepts as a plain string query or GraphQL DocumentNode. |
75| `variables` | `?object` | The variables to be used with the GraphQL request. |
76| `pause` | `?boolean` | A boolean flag instructing [execution to be paused](../basics/vue.md#pausing-usequery). |
77| `context` | `?object` | Holds the contextual information for the subscription. |
78
79Each of these inputs may also be [reactive](https://v3.vuejs.org/api/refs-api.html) (e.g. a `ref`)
80and are allowed to change over time which will issue a new query.
81
82`useSubscription` also optionally accepts a second argument, which may be a handler function with
83a type signature of:
84
85```js
86type SubscriptionHandler<T, R> = (previousData: R | undefined, data: T) => R;
87```
88
89This function will be called with the previous data (or `undefined`) and the new data that's
90incoming from a subscription event, and may be used to "reduce" the data over time, altering the
91value of `result.data`.
92
93This function returns an object with the shape of an [`OperationResult`](./core.md#operationresult)
94with an added `fetching` property, indicating whether the subscription is currently running and an
95`isPaused` property which will indicate whether `useSubscription` is currently paused.
96
97All of the properties on this result object are also marked as
98[reactive](https://v3.vuejs.org/api/refs-api.html) using `ref` and will update accordingly as the
99query is executed.
100
101The result furthermore carries several utility methods:
102
103| Method | Description |
104| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
105| `pause()` | This will pause the subscription, which is equivalent to setting `pause.value = true` |
106| `resume()` | This will resume the subscription, which is equivalent to setting `pause.value = false` |
107| `executeSubscription(opts)` | This will start a new subscription with the given partial [`Partial<OperationContext>`](./core.md#operationcontext) regardless of whether the subscription is currently paused or not. This also returns the result object again for chaining. |
108
109[Read more about how to use the `useSubscription` API on the "Subscriptions"
110page.](../advanced/subscriptions.md#vue)
111
112## useClientHandle
113
114The `useClientHandle()` function may, like the other `use*` functions, be called either in
115`setup()` or another lifecycle hook, and returns a so called "client handle". Using this `handle` we
116can access the [`Client`](./core.md#client) directly via the `client` property or call the other
117`use*` functions as methods, which will be directly bound to this `client`. This may be useful when
118chaining these methods inside an `async setup()` lifecycle function.
119
120| Method | Description |
121| ---------------------- | ------------------------------------------------------------------------------------------------------------------------- |
122| `client` | Contains the raw [`Client`](./core.md#client) reference, which allows the `Client` to be used directly. |
123| `useQuery(...)` | Accepts the same arguments as the `useQuery` function, but will always use the `Client` from the handle's context. |
124| `useMutation(...)` | Accepts the same arguments as the `useMutation` function, but will always use the `Client` from the handle's context. |
125| `useSubscription(...)` | Accepts the same arguments as the `useSubscription` function, but will always use the `Client` from the handle's context. |
126
127## Context API
128
129In Vue the [`Client`](./core.md#client) is provided either to your app or to a parent component of a
130given subtree and is then subsequently injected whenever one of the above composition functions is
131used.
132
133You can provide the `Client` from any of your components using the `provideClient` function.
134Alternatively, `@urql/vue` also has a default export of a [Vue Plugin function](https://v3.vuejs.org/guide/plugins.html#using-a-plugin).
135
136Both `provideClient` and the plugin function either accept an [instance of
137`Client`](./core.md#client) or the same options that `createClient` accepts as inputs.