fetch. NOTE: A custom implementation can also be provided instead of polyfilling, see GraphQLClient
Quick Start
First you'll need to create a client and wrap your app with the provider:
import { GraphQLClient, ClientContext } from 'graphql-hooks'const client = new GraphQLClient({ url: '/graphql'})function App() { return ( <ClientContext.Provider value={client}> {/* children */} </ClientContext.Provider> )}
Now in your child components you can make use of useQuery
import { useQuery } from 'graphql-hooks'const HOMEPAGE_QUERY = `query HomePage($limit: Int) { users(limit: $limit) { id name }}`function MyComponent() { const { loading, error, data } = useQuery(HOMEPAGE_QUERY, { variables: { limit: 10 } }) if (loading) return 'Loading...' if (error) return 'Something Bad Happened' return ( <ul> {data.users.map(({ id, name }) => ( <li key={id}>{name}</li> ))} </ul> )}
Why graphql-hooks?
The first thing you may ask when seeing graphql-hooks is "Why not use Apollo hooks?".
It's the comparison most will make. In fact, there's an article comparing the two over on LogRocket.
We believe graphql-hooks is a great choice as a hooks-first GraphQL client due to its concise API and package size.
In terms of performance, this is more of a grey area as we have no official benchmarks yet.
If you need a client that offers more customization such as advanced cache configuration, then apollo-hooks may work out to be a good choice for your project if bundle size is not an issue.
url: The URL of your GraphQL HTTP server. If not specified, you must enable fullWsTransport and provide a valid subscriptionClient; otherwise is required.
fullWsTransport: Boolean - set to true if you want to use subscriptionClient to also send query and mutations via WebSocket; defaults to false
ssrMode: Boolean - set to true when using on the server for server-side rendering; defaults to false
useGETForQueries: Boolean - set to true to use HTTP GET method for all queries; defaults to false. See HTTP Get Support for more info
subscriptionClient: The WebSocket client configuration. Accepts either an instance of SubscriptionClient from subscriptions-transport-ws or Client from graphql-ws. A factory function is also accepted e.g. to avoid the creation of the client in SSR environments.
cache (Required if ssrMode is true, otherwise optional): Object with the following methods:
fetch(url, options): Fetch implementation - defaults to the global fetch API. Check Request interceptors for more details how to manage fetch.
FormData: FormData implementation - defaults to the global FormData API. Polyfill this in a node.js environment. See file-uploads-nodejs for more info.
fetchOptions: See MDN for info on what options can be passed
headers: Object, e.g. { 'My-Header': 'hello' }
logErrors: Boolean - defaults to true
middleware: Accepts an array of middleware functions, default: none, see more in middlewares readme
onError({ operation, result }): Custom error handler
operation: Object with query, variables and operationName
result: Object containing data and error object that contains fetchError, httpError and graphqlErrors
client methods
client.setHeader(key, value): Updates client.headers adding the new header to the existing headers
client.removeHeader(key): Updates client.headers removing the header if it exists
client.logErrorResult({ operation, result }): Default error logger; useful if you'd like to use it inside your custom onError handler
request(operation, options): Make a request to your GraphQL server; returning a Promise
operation: Object with query, variables and operationName
options.fetchOptionsOverrides: Object containing additional fetch options to be added to the default ones passed to new GraphQLClient(config)
options.responseReducer: Reducer function to pick values from the original Fetch Response object. Values are merged to the request response under the data key. Example usage: {responseReducer: (data, response) => ({...data, myKey: response.headers.get('content-length)})
client.invalidateQuery(query): Will delete the older cache, re-fetch the new data using the same query, and store it in the cache as a new value
query: The GraphQL query as a plain string to be re-fetched, or an Operation object (with query, variables and operationName)
client.setQueryData(query, (oldState) => [...oldState, newState]]): Will override the older cache state with the new one provided by the function return
query: The GraphQL query as a plain string, or an Operation object (with query, variables and operationName)
(oldState) => [...oldState, newState]]: The callback function with returns will be the new state stored in the cache.
oldState: The old value stored in the cache
ClientContext
ClientContext is the result of React.createContext() - meaning it can be used directly with React's new context API:
Example:
import { ClientContext } from 'graphql-hooks'function App() { return ( <ClientContext.Provider value={client}> {/* children can now consume the client context */} </ClientContext.Provider> )}
To access the GraphQLClient instance, call React.useContext(ClientContext):
import React, { useContext } from 'react'import { ClientContext } from 'graphql-hooks'function MyComponent() { const client = useContext(ClientContext)}
useQuery
Usage:
const state = useQuery(query, [options])
Example:
import { useQuery } from 'graphql-hooks'function MyComponent() { const { loading, error, data } = useQuery(query) if (loading) return 'Loading...' if (error) return 'Something bad happened' return <div>{data.thing}</div>}
This is a custom hook that takes care of fetching your query and storing the result in the cache. It won't refetch the query unless query or options.variables changes.
query: Your GraphQL query as a plain string or DocumentNode
options: Object with the following optional properties
variables: Object e.g. { limit: 10 }
operationName: If your query has multiple operations, pass the name of the operation you wish to execute.
persisted: Boolean - defaults to false; Pass true if your graphql server supports persisted flag to serve persisted queries.
useCache: Boolean - defaults to true; cache the query result
skip: Boolean - defaults to false; do not execute the query if set to true
skipCache: Boolean - defaults to false; If true it will by-pass the cache and fetch, but the result will then be cached for subsequent calls. Note the refetch function will do this automatically
ssr: Boolean - defaults to true. Set to false if you wish to skip this query during SSR
fetchOptionsOverrides: Object - Specific overrides for this query. See MDN for info on what options can be passed
updateData(previousData, data): Function - Custom handler for merging previous & new query results; return value will replace data in useQuery return value
previousData: Previous GraphQL query or updateData result
data: New GraphQL query result
client: GraphQLClient - If a GraphQLClient is explicitly passed as an option, then it will be used instead of the client from the ClientContext.
refetchAfterMutations: String | Object | (String | Object)[] - You can specify when a mutation should trigger query refetch.
If it's a string, it's the mutation string
If it's an object then it has properties mutation and filter
mutation: String - The mutation string
refetchOnMutationError: boolean (optional, defaults to true) - It indicates whether the query must be re-fetched if the mutation returns an error
filter: Function (optional) - It receives mutation's variables as parameter and blocks refetch if it returns false
If it's an array, the elements can be of either type above
refetch(options): Function - useful when refetching the same query after a mutation; NOTE this presets skipCache=true & will bypass the options.updateData function that was passed into useQuery. You can pass a new updateData into refetch if necessary.
options: Object - options that will be merged into the options that were passed into useQuery (see above).
cacheHit: Boolean - true if the query result came from the cache, useful for debugging
error: Object - Set if at least one of the following errors has occurred and contains:
fetchError: Object - Set if an error occurred during the fetch call
httpError: Object - Set if an error response was returned from the server
graphQLErrors: Array - Populated if any errors occurred whilst resolving the query
useManualQuery
Use this when you don't want a query to automatically be fetched or wish to call a query programmatically.
The options object that can be passed either to useMutation(mutation, options) or mutationFn(options) can be set with the following properties:
variables: Object e.g. { limit: 10 }
operationName: If your query has multiple operations, pass the name of the operation you wish to execute.
fetchOptionsOverrides: Object - Specific overrides for this query. See MDN for info on what options can be passed
client: GraphQLClient - If a GraphQLClient is explicitly passed as an option, then it will be used instead of the client from the ClientContext.
onSuccess: A function to be called after the mutation has been finished with success without raising any error
In addition, there is an option to reset the current state before calling the mutation again, by calling resetFn(desiredState) where desiredState is optional and if passed, it will override the initial state with:
operation: Object - The GraphQL operation has the following properties:
query: String (required) - the GraphQL query
variables: Object (optional) - Any variables the query might need
operationName: String (optional) - If your query has multiple operations, you can choose which operation you want to call.
client: GraphQLClient - If a GraphQLClient is explicitly passed as an option, then it will be used instead of the client from the ClientContext.
callback: Function - This will be invoked when the subscription receives an event from your GraphQL server - it will receive an object with the typical GraphQL response of { data: <your result>, errors?: [Error] }
Usage:
First, follow the quick start guide to create the client and provider. Then we need to update the config for our GraphQLClient passing in the subscriptionClient:
import { GraphQLClient } from 'graphql-hooks'import { SubscriptionClient } from 'subscriptions-transport-ws'// orimport { createClient } from 'graphql-ws'const client = new GraphQLClient({ url: 'http://localhost:8000/graphql', subscriptionClient: () => new SubscriptionClient('ws://localhost:8000/graphql', { /* additional config options */ }), // or subscriptionClient: () => createClient({ url: 'ws://localhost:8000/graphql' /* additional config options */ })})
Next, within our React app, we can now make use of the useSubscription hook.
GraphQL Pagination can be implemented in various ways and it's down to the consumer to decide how to deal with the resulting data from paginated queries. Take the following query as an example of offset pagination:
In this query, the $first variable is used to limit the number of posts that are returned and the $skip variable is used to determine the offset at which to start. We can use these variables to break up large payloads into smaller chunks, or "pages". We could then choose to display these chunks as distinct pages to the user, or use an infinite loading approach and append each new chunk to the existing list of posts.
Separate pages
Here is an example where we display the paginated queries on separate pages:
import { React, useState } from 'react'import { useQuery } from 'graphql-hooks'export default function PostList() { // set a default offset of 0 to load the first page const [skipCount, setSkipCount] = useState(0) const { loading, error, data } = useQuery(allPostsQuery, { variables: { skip: skipCount, first: 10 } }) if (error) return <div>There was an error!</div> if (loading && !data) return <div>Loading</div> const { allPosts, _allPostsMeta } = data const areMorePosts = allPosts.length < _allPostsMeta.count return ( <section> <ul> {allPosts.map(post => ( <li key={post.id}> <a href={post.url}>{post.title}</a> </li> ))} </ul> <button // reduce the offset by 10 to fetch the previous page onClick={() => setSkipCount(skipCount - 10)} disabled={skipCount === 0} > Previous page </button> <button // increase the offset by 10 to fetch the next page onClick={() => setSkipCount(skipCount + 10)} disabled={!areMorePosts} > Next page </button> </section> )}
Infinite loading
Here is an example where we append each paginated query to the bottom of the current list:
import { React, useState } from 'react'import { useQuery } from 'graphql-hooks'// use options.updateData to append the new page of posts to our current list of postsconst updateData = (prevData, data) => ({ ...data, allPosts: [...prevData.allPosts, ...data.allPosts]})export default function PostList() { const [skipCount, setSkipCount] = useState(0) const { loading, error, data } = useQuery(allPostsQuery, { variables: { skip: skipCount, first: 10 }, updateData }) if (error) return <div>There was an error!</div> if (loading && !data) return <div>Loading</div> const { allPosts, _allPostsMeta } = data const areMorePosts = allPosts.length < _allPostsMeta.count return ( <section> <ul> {allPosts.map(post => ( <li key={post.id}> <a href={post.url}>{post.title}</a> </li> ))} </ul> {areMorePosts && ( <button // set the offset to the current number of posts to fetch the next page onClick={() => setSkipCount(allPosts.length)} > Show more </button> )} </section> )}
Refetch queries with mutations subscription
We can have a query to automatically refetch when any mutation from a provided list is executed.
In the following example we are refetching a list of posts for a given user.
graphql-hooks complies with the GraphQL multipart request spec, allowing files to be used as query or mutation arguments. The same spec is also supported by popular GraphQL servers, including Apollo Server (see list of supported servers here).
If there are files to upload, the request's body will be a FormData instance conforming to the GraphQL multipart request spec.
Using GET for queries can be useful, especially when implementing any sort of HTTP caching strategy. There are two ways you can do this:
Per Query
const { loading, error, data } = useQuery(MY_QUERY, { fetchOptionsOverrides: { method: 'GET' }})// same goes for useManualQueryconst [fetchSomething] = useManualQuery(MY_QUERY, { fetchOptionsOverrides: { method: 'GET' }})
For All Queries
When you create your client, set the useGETForQueries option as true:
const client = new GraphQLClient({ url: '/graphql', useGETForQueries: true})
Authentication
You can have access to the graphql-hooks client context by using React's new context API. ClientContext is actually the result of React.createContext().
In the above example we use useContext() hook to get access to the graphql-hooks clientContext.
Then we request the token from the server by performing the loginUser mutation.
In the case the login is successful we set the token to the client's header (client.setHeader), otherwise we need to handle the error.
For more information about graphql-hooks clientContext refer to GraphQLClient section.
Fragments
Coming soon!
Migrating from Apollo
For a real life example, compare the next.js with-apollo vs with-graphql-hooks. We have feature parity and the main-*.js bundle is a whopping 93% smaller (7.9KB vs 116KB).
ApolloClient ➡️ GraphQLClient
- import { ApolloClient } from 'apollo-client'- import { InMemoryCache } from 'apollo-cache-inmemory'+ import { GraphQLClient } from 'graphql-hooks'+ import memCache from 'graphql-hooks-memcache'- const client = new ApolloClient({- uri: '/graphql',- cache: new InMemoryCache()- })+ const client = new GraphQLClient({+ url: '/graphql',+ cache: memCache()+ })
A lot of the options you'd pass to ApolloClient are the same as GraphQLClient:
uri ➡️ url
fetchOptions
onError - the function signature is slightly different
headers
fetch
cache
ApolloProvider ➡️ ClientContext.Provider
- import { ApolloProvider } from 'react-apollo'+ import { ClientContext } from 'graphql-hooks'function App({ client }) { return (- <ApolloProvider client={client}>+ <ClientContext.Provider value={client}> {/* children */}+ </ClientContext.Provider>- </ApolloProvider> )}
Query Component ➡️ useQuery
- import { Query } from 'react-apollo'- import gql from 'graphql-tag'+ import { useQuery } from 'graphql-hooks'function MyComponent() {+ const { loading, error, data } = useQuery('...')- return (- <Query query={gql`...`}>- {({ loading, error, data}) => { if (loading) return 'Loading...' if (error) return 'Error :(' return <div>{data}</div>- }}- </Query>- )}
Query Component Props
A lot of options can be carried over as-is, or have direct replacements:
query ➡️ useQuery(query): Remove any usage of gql and pass your queries as strings.
The LocalGraphQLClient will return data and error properties in the same format as the GraphQLClient
Variables
Variables can be used in the local mock queries given to the LocalGraphQLClient, which can then be supplied to the request function:
const localQueries = { AddNumbersQuery: ({ a, b }) => ({ addedNumber: a + b })}const client = new LocalGraphQLClient({ localQueries })const result = await client.request({ query: 'AddNumbersQuery', variables: { a: 2, b: 3 }})console.log(result.data.addedNumber) // Will be 5
Error mocking
Errors can be simply mocked in LocalGraphQLClient queries by using the LocalGraphQLError class:
// test/Post.test.tsximport { allPostsQuery } from '../src/components/Post'const localQueries = { [allPostsQuery]: () => new LocalGraphQLError({ httpError: { status: 404, statusText: 'Not found', body: 'Not found' } })}const client = new LocalGraphQLClient({ localQueries })const result = await client.request({ query: allPostsQuery})console.log(result.error) // The `error` object will have an `httpError`
It is also possible to mock a partial error response (for example where one resolver encounters an error but other resolvers return successfully). To do this, include Error objects in the mock query resolver:
import { allPostsQuery } from '../src/components/Post'const localQueries = { [allPostsQuery]: () => ({ field1: 'foo', field2: new Error('something went wrong'), nested: { field3: new Error('a nested error') } })}const client = new LocalGraphQLClient({ localQueries })const result = await client.request({ query: allPostsQuery})console.log(result.data) // The `data` object will have the correct value for `field1` and `null` for any fields returning `Error` objectsconsole.log(result.error) // The `error` object will have a `graphQLErrors` array containing each of the `Error` objects created above
The test-utils.js is a good example of how to create a custom render function using @testing-library/react which can wrap the render of a React component in a ClientContext setup to use the LocalGraphQLClient with supplied local queries:
Because the LocalGraphQLClient just uses the localQueries object supplied to it, it is possible to modify or spy the local queries during tests. For example:
it('shows "No posts" if 0 posts are returned', async () => { jest.spyOn(localQueries, allPostsQuery).mockImplementation(() => ({ allPosts: [] })) render(<Posts />, { localQueries }) expect(await screen.findByText('No posts')).toBeTruthy()})
Typescript Support
All client methods support the ability to provide type information for response data, query variables and error responses.
import { useQuery } from 'graphql-hooks'type User = { id: string name: string}type CustomError = { message: string extensions?: Record<string, any>}const HOMEPAGE_QUERY = `query HomePage($limit: Int) { users(limit: $limit) { id name }}`function MyComponent() { const { loading, error, data } = useQuery< User, { limit: number }, CustomError >(HOMEPAGE_QUERY, { variables: { limit: 10 } }) if (loading) return 'Loading...' if (error) return 'Something Bad Happened' return ( <ul> {data.users.map(({ id, name }) => ( <li key={id}>{name}</li> ))} </ul> )}
graphql-hooks also supports TypedDocumentNode. This allows you to use GraphQL code gen to create DocumentNodes for your GQL queries and receive full type support.
import { useQuery } from 'graphql-hooks'import { graphql } from './gql'const HOMEPAGE_QUERY = graphql(`query HomePage($limit: Int) { users(limit: $limit) { id name }}`)function MyComponent() { // data will be typed as User objects with id, name properties const { loading, error, data } = useQuery(HOMEPAGE_QUERY, { variables: { limit: 10 } }) if (loading) return 'Loading...' if (error) return 'Something Bad Happened' return ( <ul> {data.users.map(({ id, name }) => ( <li key={id}>{name}</li> ))} </ul> )}
Full details of the features of TypedDocumentNode and GraphQL Code Generator can be found here. Full examples of this implementation are in the examples folder.
Other
Request interceptors
It is possible to provide a custom library to handle network requests. Having that there is more control on how to handle the requests. The following example shows how to supply axios HTTP client with interceptors. It can be handy in the situations where JWT token has expired, needs to be refreshed and request retried.
import axios from 'axios'import { buildAxiosFetch } from '@lifeomic/axios-fetch'import { GraphQLClient } from 'graphql-hooks'const gqlAxios = axios.create()gqlAxios.interceptors.response.use( function (response) { return response }, function (error) { // Handle expired JWT and refresh token })const client = new GraphQLClient({ url: '/graphql', fetch: buildAxiosFetch(gqlAxios)})
AbortController
if you wish to abort a fetch it is possible to pass an AbortController signal to the fetchOptionsOverrides option of the fetch function. This is not graphql-hooks specific functionality, rather just an example of how to use it with the library.
As well as supporting input of your queries as strings, this library also supports using a DocumentNode. Document nodes can be generated using a code-generation tool such as GraphQL codegen which will provide typing information for your queries based on your GraphQL schema (see the typescript example). If you don't want to use a code-generation library you can use graphql-tag to generate a DocumentNode.
We now use GitHub Discussions for our community. To join, click on "Discussions". We encourage you to start a new discussion, share some ideas or ask questions from the community.
If you want to see the old community posts (on Spectrum) you can access them here.
Contributors
Thanks goes to these wonderful people (emoji key):