Interface ClientOptions

Configuration options passed when creating a new Client.


The ClientOptions are passed when creating a new Client, and are used to instantiate the pipeline of Exchanges, configure options used to initialize OperationContexts, or to change the general behaviour of the Client.


  • ClientOptions


exchanges: Exchange[]

A list of Exchanges that will be used to create the Client's execution pipeline.


The Client accepts and composes a list of Exchanges into an “exchange pipeline” which receive a stream of Operations the Client wishes to execute, and return a stream of OperationResults.

This is the basis for how urql handles GraphQL operations, and exchanges handle the creation, execution, and control flow of exchanges for the Client.

To easily get started you should consider using the dedupExchange, cacheExchange and fetchExchange these are all exported from the core package.

See for more information on what Exchanges are and how they work.

fetch?: ((input, init?) => Promise<Response>)

Type declaration

    • (input, init?): Promise<Response>
    • A fetch function polyfill used by fetch exchanges to make API calls.


      This is the fetch polyfill used by any fetch exchange to make an API request. By default, when this option isn't set, any fetch exchange will attempt to use the globally available fetch function to make a request instead.

      It's recommended to only pass a polyfill, if any of the environments you're running the Client in don't support the Fetch API natively.

      Hint: If you're using the "Incremental Delivery" multipart spec, for instance with @defer directives, you're better off using the native fetch function, or must ensure that your polyfill supports streamed results. However, a "Streaming requests unsupported" error will be thrown, to let you know that your fetch API doesn't support incrementally streamed responses, if this mode is used.

      See for the Fetch API spec.


      Returns Promise<Response>

fetchOptions?: RequestInit | (() => RequestInit)

Additional options used by fetch exchanges that'll be passed to the fetch call on API requests.


The options in this object or an object returned by a callback function will be merged into the RequestInit options passed to the fetch call.

Hint: If you're trying to implement more complex changes per Operation, it's worth considering to use the mapExchange instead, which allows you to change Operations and OperationResults.

Hint: If you're trying to use this as a function for authentication, consider checking out @urql/exchange-auth instead, which allows you to handle refresh auth flows, and more complex auth flows.

See for a description of this object.

fetchSubscriptions?: boolean

Allows a subscription to be executed using a fetch API request.


If your API supports the text/event-stream and/or multipart/mixed response protocol, and you use this protocol to handle subscriptions, then you may switch this flag to true.

This means you won’t have to create a subscriptionExchange to handle subscriptions with an external transport, and will instead be able to use GraphQL over HTTP transports.

maskTypename?: boolean

Instructs the Client to remove __typename properties on all results.


By default, cache exchanges will alter your GraphQL documents to request __typename fields for all selections. However, this means that your GraphQL data will now contain __typename fields you didn't ask for. This is why the Client supports “masking” this field by marking it as non-enumerable via this option.

Only use this option if you absolutely have to. It's popular to model mutation inputs in GraphQL schemas after the object types they modify, and if you're using this option to make it possible to directly pass objects from results as inputs to your mutation variables, it's more performant and idomatic to instead create a new input object.

Hint: With @urql/exchange-graphcache you will never need this option, as it selects fields on the client-side according to which fields you specified, rather than the fields it modified.

See for more information on typename introspection via the __typename field.

preferGetMethod?: boolean | "force" | "within-url-limit"

Instructs fetch exchanges to use a GET request.


This changes the preferGetMethod option, which tells fetch exchanges to use GET requests for queries instead of POST requests.

When set to true or 'within-url-limit', built-in fetch exchanges will always attempt to send query operations as GET requests, unless the resulting URL exceeds a length of 2,048 characters. If you want to bypass this restriction, set this option to 'force' instead, to always send GET. requests for queries.

requestPolicy?: RequestPolicy

The request and caching strategy that all Operations on this Client will use by default.


The RequestPolicy instructs cache exchanges how to use and treat their cached results. By default cache-first is set and used, which will use cache results, and only make an API request on a cache miss.

The requestPolicy can be overriden per operation, since it's added to the OperationContext, which allows you to change the policy per Operation, rather than changing it by default here.

Hint: We don’t recommend changing this from the default cache-first option, unless you know what you‘re doing. Setting this to cache-and-network is not recommend and may not lead to the behaviour you expect. If you’re looking to always update your cache frequently, use @urql/exchange-request-policy instead.

suspense?: boolean

A configuration flag indicating whether support for "Suspense" is activated.


This configuration flag is only relevant for using urql with the React or Preact bindings. When activated it allows useQuery to "suspend" instead of returning a loading state, which will stop updates in a querying component and instead cascade to a higher suspense boundary for a loading state.

Hint: While, when this option is enabled, by default all useQuery hooks will suspense, you can disable Suspense selectively for each hook.

See for more information on React Suspense.

url: string

Target URL used by fetch exchanges to make GraphQL API requests to.


This is the URL that fetch exchanges will call to make GraphQL API requests. This value is copied to url.

Generated using TypeDoc