Vue API

useQuery

Accepts a single required options object as an input with the following properties:

PropTypeDescription
querystring | DocumentNodeThe query to be executed. Accepts as a plain string query or GraphQL DocumentNode.
variables?objectThe variables to be used with the GraphQL request.
requestPolicy?RequestPolicyAn optional request policy that should be used specifying the cache strategy.
pause?booleanA boolean flag instructing execution to be paused.
context?objectHolds the contextual information for the query.

Each of these inputs may also be reactive (e.g. a ref) and are allowed to change over time which will issue a new query.

This function returns an object with the shape of an OperationResult with an added fetching property, indicating whether the query is currently being fetched and an isPaused property which will indicate whether useQuery is currently paused and won't automatically start querying.

All of the properties on this result object are also marked as reactive using ref and will update accordingly as the query is executed.

The result furthermore carries several utility methods:

MethodDescription
pause()This will pause automatic querying, which is equivalent to setting pause.value = true
resume()This will resume a paused automatic querying, which is equivalent to setting pause.value = false
executeQuery(opts)This will execute a new query with the given partial Partial<OperationContext> regardless of whether the query is currently paused or not. This also returns the result object again for chaining.

Furthermore the returned result object of useQuery is also a PromiseLike, which allows you to take advantage of Vue 3's experimental Suspense feature. When the promise is used, e.g. you await useQuery(...) then the PromiseLike will only resolve once a result from the API is available.

Read more about how to use the useQuery API on the "Queries" page.

useMutation

Accepts a single query argument of type string | DocumentNode and returns a result object with the shape of an OperationResult with an added fetching property.

All of the properties on this result object are also marked as reactive using ref and will update accordingly as the mutation is executed.

The object also carries a special executeMutation method, which accepts variables and optionally a Partial<OperationContext> and may be used to start executing a mutation. It returns a Promise resolving to an OperationResult

Read more about how to use the useMutation API on the "Mutations" page.

useSubscription

Accepts a single required options object as an input with the following properties:

PropTypeDescription
querystring | DocumentNodeThe query to be executed. Accepts as a plain string query or GraphQL DocumentNode.
variables?objectThe variables to be used with the GraphQL request.
pause?booleanA boolean flag instructing execution to be paused.
context?objectHolds the contextual information for the subscription.

Each of these inputs may also be reactive (e.g. a ref) and are allowed to change over time which will issue a new query.

useSubscription also optionally accepts a second argument, which may be a handler function with a type signature of:

type SubscriptionHandler<T, R> = (previousData: R | undefined, data: T) => R;

This function will be called with the previous data (or undefined) and the new data that's incoming from a subscription event, and may be used to "reduce" the data over time, altering the value of result.data.

This function returns an object with the shape of an OperationResult with an added fetching property, indicating whether the subscription is currently running and an isPaused property which will indicate whether useSubscription is currently paused.

All of the properties on this result object are also marked as reactive using ref and will update accordingly as the query is executed.

The result furthermore carries several utility methods:

MethodDescription
pause()This will pause the subscription, which is equivalent to setting pause.value = true
resume()This will resume the subscription, which is equivalent to setting pause.value = false
executeSubscription(opts)This will start a new subscription with the given partial Partial<OperationContext> regardless of whether the subscription is currently paused or not. This also returns the result object again for chaining.

Read more about how to use the useSubscription API on the "Subscriptions" page.

useClientHandle

The useClientHandle() function may, like the other use* functions, be called either in setup() or another lifecycle hook, and returns a so called "client handle". Using this handle we can access the Client directly via the client property or call the other use* functions as methods, which will be directly bound to this client. This may be useful when chaining these methods inside an async setup() lifecycle function.

MethodDescription
clientContains the raw Client reference, which allows the Client to be used directly.
useQuery(...)Accepts the same arguments as the useQuery function, but will always use the Client from the handle's context.
useMutation(...)Accepts the same arguments as the useMutation function, but will always use the Client from the handle's context.
useSubscription(...)Accepts the same arguments as the useSubscription function, but will always use the Client from the handle's context.

Context API

In Vue the Client is provided either to your app or to a parent component of a given subtree and is then subsequently injected whenever one of the above composition functions is used.

You can provide the Client from any of your components using the provideClient function. Alternatively, @urql/vue also has a default export of a Vue Plugin function.

Both provideClient and the plugin function either accept an instance of Client or the same options that createClient accepts as inputs.