π£ Minimal hooks-first GraphQL client.
- π₯ First-class hooks API
- βοΈ Tiny bundle: only 22.9kB (7.4kB gzipped)
- π Full SSR support: see graphql-hooks-ssr
- π Plugin Caching: see graphql-hooks-memcache
- π₯ No more render props hell
- β³ Handle loading and error states with ease
npm install graphql-hooks
or
yarn add graphql-hooks
- Node LTS
- Browsers
> 1%, not dead
Consider polyfilling:
FormData
Promise
fetch
. NOTE: A custom implementation can also be provided instead of polyfilling, seeGraphQLClient
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>
)
}
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.
Pros | Cons |
---|---|
Small in size | Less "advanced" caching configuration |
Concise API | |
Quick to get up and running |
- API
- Guides
Usage:
import { GraphQLClient } from 'graphql-hooks'
const client = new GraphQLClient(config)
config
: Object containing configuration properties
url
: The URL of your GraphQL HTTP server. If not specified, you must enablefullWsTransport
and provide a validsubscriptionClient
; otherwise is required.fullWsTransport
: Boolean - set totrue
if you want to usesubscriptionClient
to also send query and mutations via WebSocket; defaults tofalse
ssrMode
: Boolean - set totrue
when using on the server for server-side rendering; defaults tofalse
useGETForQueries
: Boolean - set totrue
to use HTTP GET method for all queries; defaults to false. See HTTP Get Support for more infosubscriptionClient
: The WebSocket client configuration. Accepts either an instance ofSubscriptionClient
from subscriptions-transport-ws orClient
from graphql-ws. A factory function is also accepted e.g. to avoid the creation of the client in SSR environments.cache
(Required ifssrMode
istrue
, otherwise optional): Object with the following methods:cache.get(key)
cache.set(key, data)
cache.delete(key)
cache.clear()
cache.keys()
getInitialState()
- See graphql-hooks-memcache as a reference implementation
fetch(url, options)
: Fetch implementation - defaults to the globalfetch
API. Check Request interceptors for more details how to managefetch
.FormData
: FormData implementation - defaults to the globalFormData
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 passedheaders
: Object, e.g.{ 'My-Header': 'hello' }
logErrors
: Boolean - defaults totrue
middleware
: Accepts an array of middleware functions, default: none, see more in middlewares readmeonError({ operation, result })
: Custom error handleroperation
: Object withquery
,variables
andoperationName
result
: Object containingdata
,headers
anderror
object that containsfetchError
,httpError
andgraphqlErrors
client.setHeader(key, value)
: Updatesclient.headers
adding the new header to the existing headersclient.setHeaders(headers)
: Replacesclient.headers
client.removeHeader(key)
: Updatesclient.headers
removing the header if it existsclient.logErrorResult({ operation, result })
: Default error logger; useful if you'd like to use it inside your customonError
handlerrequest(operation, options)
: Make a request to your GraphQL server; returning a Promiseoperation
: Object withquery
,variables
andoperationName
options.fetchOptionsOverrides
: Object containing additional fetch options to be added to the default ones passed tonew GraphQLClient(config)
options.responseReducer
: Reducer function to pick values from the original Fetch Response object. Values are merged to therequest
response under thedata
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 valuequery
: The GraphQL query as a plain string to be re-fetched, or an Operation object (withquery
,variables
andoperationName
)
client.setQueryData(query, (oldState) => [...oldState, newState]])
: Will override the older cache state with the new one provided by the function returnquery
: The GraphQL query as a plain string, or an Operation object (withquery
,variables
andoperationName
)(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
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)
}
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 DocumentNodeoptions
: Object with the following optional propertiesvariables
: 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 tofalse
; Passtrue
if your graphql server supportspersisted
flag to serve persisted queries.useCache
: Boolean - defaults totrue
; cache the query resultskip
: Boolean - defaults tofalse
; do not execute the query if set totrue
skipCache
: Boolean - defaults tofalse
; Iftrue
it will by-pass the cache and fetch, but the result will then be cached for subsequent calls. Note therefetch
function will do this automaticallyssr
: Boolean - defaults totrue
. Set tofalse
if you wish to skip this query during SSRfetchOptionsOverrides
: Object - Specific overrides for this query. See MDN for info on what options can be passedupdateData(previousData, data)
: Function - Custom handler for merging previous & new query results; return value will replacedata
inuseQuery
return valuepreviousData
: Previous GraphQL query orupdateData
resultdata
: 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 theClientContext
.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 stringrefetchOnMutationError
: boolean (optional, defaults totrue
) - It indicates whether the query must be re-fetched if the mutation returns an errorfilter
: 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
const { loading, error, data, refetch, cacheHit } = useQuery(QUERY)
loading
: Boolean -true
if the query is in flightdata
: Object - the result of your GraphQL queryheaders
: Object - response headersrefetch(options)
: Function - useful when refetching the same query after a mutation; NOTE this presetsskipCache=true
& will bypass theoptions.updateData
function that was passed intouseQuery
. You can pass a newupdateData
intorefetch
if necessary.options
: Object - options that will be merged into theoptions
that were passed intouseQuery
(see above).
cacheHit
: Boolean -true
if the query result came from the cache, useful for debuggingerror
: Object - Set if at least one of the following errors has occurred and contains:fetchError
: Object - Set if an error occurred during thefetch
callhttpError
: Object - Set if an error response was returned from the servergraphQLErrors
: Array - Populated if any errors occurred whilst resolving the query
Use this when you don't want a query to automatically be fetched or wish to call a query programmatically.
Usage:
const [queryFn, state] = useManualQuery(query, [options])
Example:
import { useManualQuery } from 'graphql-hooks'
function MyComponent(props) {
const [fetchUser, { loading, error, data }] = useManualQuery(GET_USER_QUERY, {
variables: { id: props.userId }
})
return (
<div>
<button onClick={fetchUser}>Get User!</button>
{error && <div>Failed to fetch user<div>}
{loading && <div>Loading...</div>}
{data && <div>Hello ${data.user.name}</div>}
</div>
)
}
If you don't know certain options when declaring the useManualQuery
you can also pass the same options to the query function itself when calling it:
import { useManualQuery } from 'graphql-hooks'
function MyComponent(props) {
const [fetchUser] = useManualQuery(GET_USER_QUERY)
const fetchUserThenSomething = async () => {
const user = await fetchUser({
variables: { id: props.userId }
})
return somethingElse()
}
return (
<div>
<button onClick={fetchUserThenSomething}>Get User!</button>
</div>
)
}
Will return the graphql client provided to ClientContext.Provider
as value
Usage:
const client = useQueryClient()
Example:
import { useQueryClient } from 'graphql-hooks'
function MyComponent() {
const client = useQueryClient()
return <div>...</div>
}
Mutations unlike Queries are not cached.
Usage:
const [mutationFn, state, resetFn] = useMutation(mutation, [options])
Example:
import { useMutation } from 'graphql-hooks'
const UPDATE_USER_MUTATION = `mutation UpdateUser(id: String!, name: String!) {
updateUser(id: $id, name: $name) {
name
}
}`
function MyComponent({ id, name }) {
const [updateUser] = useMutation(UPDATE_USER_MUTATION)
const [newName, setNewName] = useState(name)
return (
<div>
<input
type="text"
value={newName}
onChange={e => setNewName(e.target.value)}
/>
<button
onClick={() => updateUser({ variables: { id, name: newName } })}
/>
</div>
)
}
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 passedclient
: GraphQLClient - If a GraphQLClient is explicitly passed as an option, then it will be used instead of the client from theClientContext
.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:
data
: Object - the dataheaders
: Object - response headerserror
: Error - the errorloading
: Boolean - true if it is still loadingcacheHit
: Boolean - true if the result was cached
To use subscription you can use either subscriptions-transport-ws or graphql-ws
API
useSubscription(operation, callback)
operation
: Object - The GraphQL operation has the following properties:query
: String (required) - the GraphQL queryvariables
: Object (optional) - Any variables the query might needoperationName
: 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 theClientContext
.
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'
// or
import { createClient } from 'graphql-ws'
const client = new GraphQLClient({
url: 'https://localhost:8000/graphql',
subscriptionClient: () =>
new SubscriptionClient('ws:https://localhost:8000/graphql', {
/* additional config options */
}),
// or
subscriptionClient: () =>
createClient({
url: 'ws:https://localhost:8000/graphql'
/* additional config options */
})
})
Next, within our React app, we can now make use of the useSubscription
hook.
import React, { useState } from 'react'
import { useSubscription } from 'graphql-hooks'
const TOTAL_COUNT_SUBSCRIPTION = `
subscription TotalCount {
totalCount {
count
}
}
`
function TotalCountComponent() {
const [count, setCount] = useState(0)
const [error, setError] = useState(null)
useSubscription({ query: TOTAL_COUNT_SUBSCRIPTION }, ({ data, errors }) => {
if (errors && errors.length > 0) {
// handle your errors
setError(errors[0])
return
}
// all good, handle the gql result
setCount(data.totalCount.count)
})
if (error) {
return <span>An error occurred {error.message}</span>
}
return <div>Current count: {count}</div>
}
Working Example:
See our subscription example which has both the client and server code to integrate subscriptions into your application.
See also the full WS transport example if you want to see how to send every operation through WebSocket.
See graphql-hooks-ssr for an in depth guide.
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:
export const allPostsQuery = `
query allPosts($first: Int!, $skip: Int!) {
allPosts(first: $first, skip: $skip) {
id
title
url
}
_allPostsMeta {
count
}
}
`
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.
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>
)
}
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 posts
const 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>
)
}
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.
Example
export const allPostsByUserIdQuery = `
query allPosts($userId: Int!) {
allPosts(userId: $userId) {
id
title
url
}
}
`
export const createPostMutation = `
mutation createPost($userId: Int!, $text: String!) {
createPost(userId: $userId, text: $text) {
id
title
url
}
}
`
const myUserId = 5
useQuery(allPostsByUserIdQuery, {
variables: {
userId: myUserId
},
refetchAfterMutations: [
{
mutation: createPostMutation,
filter: variables => variables.userId === myUserId
}
]
})
There are two ways to reach that:
import { useMutation, useQueryClient } from 'graphql-hooks'
import React from 'react'
const MY_MUTATION = `...`
const MY_QUERY = `...`
export default function MyComponent() {
const client = useQueryClient()
const [applyMutation, { ... }] = useMutation(MY_MUTATION, {
onSuccess: () => client.invalidateQuery(MY_QUERY)
})
return (
...
)
}
import { useMutation, useQueryClient } from 'graphql-hooks'
import React from 'react'
const MY_MUTATION = `...`
const MY_QUERY = `...`
export default function MyComponent() {
const client = useQueryClient()
const [applyMutation, { ... }] = useMutation(MY_MUTATION, {
onSuccess: (result) => {
client.setQueryData(MY_QUERY, oldState => [
...oldState,
result,
])
}
})
return (
...
)
}
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.
import React, { useRef } from 'react'
import { useMutation } from 'graphql-hooks'
const uploadPostPictureMutation = `
mutation UploadPostPicture($picture: Upload!) {
uploadPostPicture(picture: $picture) {
id
pictureUrl
}
}
`
export default function PostForm() {
// File input is always uncontrolled in React.
// See: https://reactjs.org/docs/uncontrolled-components.html#the-file-input-tag.
const fileInputRef = useRef(null)
const [uploadPostPicture] = useMutation(uploadPostPictureMutation)
const handleSubmit = event => {
event.preventDefault()
uploadPostPicture({
variables: {
picture: fileInputRef.current.files[0]
}
})
}
return (
<form onSubmit={handleSubmit}>
<input accept="image/*" ref={fileInputRef} type="file" />
<button>Upload</button>
</form>
)
}
import { FormData } from 'formdata-node'
import { fileFromPath } from 'formdata-node/file-from-path'
const client = new GraphQLClient({
url: 'https://domain.com/graphql',
fetch: require('node-fetch'),
FormData
})
const uploadPostPictureMutation = `
mutation UploadPostPicture($picture: Upload!) {
uploadPostPicture(picture: $picture) {
id
pictureUrl
}
}
`
const { data, error } = await client.request({
query: uploadPostPictureMutation,
variables: { picture: await fileFromPath('some-file.txt') }
})
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 useManualQuery
const [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
})
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()
.
Login Example
import React, { useState, useContext } from 'react'
import { useMutation, ClientContext } from 'graphql-hooks'
const LOGIN_MUTATION = `mutation LoginUser (name: String!, password: String!) {
loginUser(name: $name, password: $password) {
token
}
}`
const Login = () => {
const client = useContext(ClientContext)
const [loginUserMutation] = useMutation(LOGIN_MUTATION)
const [userName, setUserName] = useState()
const [password, setPassword] = useState()
const handleLogin = async e => {
e.preventDefault()
const { data, error } = await loginUserMutation({
variables: { userName, password }
})
if (error) {
// your code to handle login error
} else {
const { token } = data.loginUser
client.setHeader('Authorization', `Bearer ${token}`)
// your code to handle token in browser and login redirection
}
}
return (
<form onSubmit={handleLogin}>
User Name:{' '}
<input
type={'text'}
value={userName}
onChange={e => setUserName(e.target.value)}
/>
PassWord: <input
type={'password'}
value={password}
onChange={e => setPassword(e.target.value)}
/>
<input type={'submit'} value={'Login'} />
</form>
)
}
export default Login
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.
Coming soon!
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).
- 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 differentheaders
fetch
cache
- 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>
)
}
- 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>
- )
}
A lot of options can be carried over as-is, or have direct replacements:
query
β‘οΈuseQuery(query)
: Remove any usage ofgql
and pass your queries as strings.variables
β‘οΈuseQuery(query, { variables })
ssr
β‘οΈuseQuery(query, { ssr })
- Fetch Policies: See #75 for more info
cache-first
: This is the default behaviour ofgraphql-hooks
cache-and-network
: The refetch function provides this behavior it will set loading: true, but the old data will be still set until the fetch resolves.network-only
β‘οΈuseQuery(QUERY, { skipCache: true })
cache-only
: Not supportedno-cache
β‘οΈuseQuery(QUERY, { useCache: false })
Not yet supported
errorPolicy
: Any error will set theerror
to be truthy. See useQuery for more details.pollInterval
notifyOnNetworkStatusChange
skip
onCompleted
: Similar ability if usinguseManualQuery
onError
: Similar ability if usinguseManualQuery
partialRefetch
- <Query query={gql`...`}>
- {(props) => {}}
- </Query>
+ const state = useQuery(`...`)
props.loading
β‘οΈconst { loading } = useQuery('...')
props.error
β‘οΈconst { error } = useQuery('...')
: The error value fromuseQuery
is Boolean the details of the error can be found in either:state.fetchError
state.httpError
state.graphQLErrors
props.refetch
οΈβ‘οΈconst { refetch } = useQuery('...')
props.updateData(prevResult, options)
οΈβ‘οΈstate.updateData(prevResult, newResult)
Not yet supported
props.networkStatus
props.startPolling
props.stopPolling
props.subscribeToMore
- import { Mutation } from 'react-apollo'
- import gql from 'graphql-tag'
+ import { useMutation } from 'graphql-hooks'
function MyComponent() {
+ const [mutateFn, { loading, error, data }] = useMutation('...')
- return (
- <Mutation mutation={gql`...`}>
- {(mutateFn, { loading, error }) => {
if (error) return 'Error :('
return <button disabled={loading} onClick={() => mutateFn()}>Submit</button>
- }}
- </Mutation>
- )
}
mutation
β‘οΈuseMutation(mutation)
- no need to wrap it ingql
variables
β‘οΈοΈuseMutation(mutation, { variables })
ormutateFn({ variables })
ignoreResults
β‘οΈοΈοΈοΈconst [mutateFn] = useMutation(mutation)
onCompleted
β‘οΈ οΈmutateFn().then(onCompleted)
onError
β‘οΈmutateFn().then(({ error }) => {...})
Not yet supported
update
: Coming soon #52optimisticResponse
refetchQueries
awaitRefetchQueries
context
- <Mutation mutation={gql`...`}>
- {(mutateFn, props) => {}}
- </Mutation>
+ const [mutateFn, state] = useMutation(`...`)
props.data
β‘οΈconst [mutateFn, { data }] = useMutation()
props.loading
β‘οΈconst [mutateFn, { loading }] = useMutation()
props.error
β‘οΈconst [mutateFn, { error }] = useMutation()
: The the details of the error can be found in either:state.fetchError
state.httpError
state.graphQLErrors
client
οΈβ‘οΈοΈconst client = useContext(ClientContext)
see ClientContext
Not yet supported
called
There is a LocalGraphQLClient
class you can use to mock requests without a server for testing or development purposes.
This client inherits from GraphQLClient
and provides the same API, but doesn't connect to any server and instead responds to pre-defined queries.
It needs to be supplied on creation with a localQueries
object, which is an object where:
- the keys are the queries defined in the application;
- the values are query functions returning the mocked data.
// src/components/Post.js
export const allPostsQuery = `
query {
allPosts {
id
title
url
}
}
`
// test/Post.test.tsx
import { allPostsQuery, createPostMutation } from '../src/components/Post'
const localQueries = {
[allPostsQuery]: () => ({
allPosts: [
{
id: 1,
title: 'Test',
url: 'https://example.com'
}
]
}),
[createPostMutation]: () => ({ createPost: { id: 1 } })
}
const client = new LocalGraphQLClient({ localQueries })
const { data, error } = await client.request({
query: allPostsQuery
})
The LocalGraphQLClient
will return data
and error
properties in the same format as the GraphQLClient
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
Errors can be simply mocked in LocalGraphQLClient
queries by using the LocalGraphQLError
class:
// test/Post.test.tsx
import { 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` objects
console.log(result.error) // The `error` object will have a `graphQLErrors` array containing each of the `Error` objects created above
Example tests that use the LocalGraphQLClient
are provided in the examples/create-react-app/test folder.
The test-utils.tsx 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:
const customRender = (ui, options) => {
const client = new LocalGraphQLClient({
localQueries: options.localQueries
})
const Wrapper = ({ children }) => {
return (
<ClientContext.Provider value={client}>{children}</ClientContext.Provider>
)
}
Wrapper.propTypes = {
children: T.node.isRequired
}
return render(ui, {
wrapper: Wrapper,
...options
})
}
export * from '@testing-library/react'
export { customRender as render }
Using this allows us to easily render a component using the LocalGraphQLClient
with local queries when writing tests:
// Comes from the above code
import { render, screen } from './test-utils'
const localQueries = {
[allPostsQuery]: () => ({
allPosts: [
{
id: 1,
title: 'Test',
url: 'https://example.com'
}
]
})
}
describe('Posts', () => {
it('should render successfully', async () => {
render(<Posts />, {
localQueries
})
expect(
await screen.findByRole('link', {
name: /Test/i
})
).toBeTruthy()
})
})
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()
})
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 DocumentNode
s 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.
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)
})
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.
import { useManualQuery } from 'graphql-hooks'
function AbortControllerExample() {
const abortControllerRef = useRef()
const [fetchData, { loading }] = useManualQuery(`...`)
const handleFetch = () => {
abortControllerRef.current = new AbortController()
const { signal } = abortControllerRef.current
fetchData({
fetchOptionsOverrides: {
signal
}
})
}
const handleAbort = () => {
abortControllerRef.current?.abort()
}
return (
<>
<button onClick={handleFetch}>Fetch Data</button>
{loading && <button onClick={handleAbort}>Abort</button>}
</>
)
}
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
.
import gql from 'graphql-tag'
const allPostsQuery = gql`
query {
posts {
id
name
}
}
`
function Posts() {
const { loading, error, data, refetch } = useQuery(allPostsQuery)
return (
<>
<h2>Add post</h2>
<AddPost />
<h2>Posts</h2>
<button onClick={() => refetch()}>Reload</button>
<PostList loading={loading} error={error} data={data} />
</>
)
}
...
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.
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind are welcome!