graphql-hooks
Advanced tools
🎣 Minimal hooks-first GraphQL client.
npm install graphql-hooks
or
yarn add graphql-hooks
> 1%, not deadConsider polyfilling:
FormDataPromisefetch. NOTE: A custom implementation can also be provided instead of polyfilling, see GraphQLClientFirst 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>
)
}
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 middleware and 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 | Middleware support |
| Concise API | Less "advanced" caching configuration |
| Quick to get up and running |
GraphQLClientUsage:
import { GraphQLClient } from 'graphql-hooks'
const client = new GraphQLClient(config)
config: Object containing configuration properties
url (Required): The url to your GraphQL serverssrMode: Boolean - set to true when using on the server for server-side rendering; defaults to falseuseGETForQueries: Boolean - set to true to use HTTP GET method for all queries; defaults to false. See HTTP Get Support for more infosubscriptionClient: An instance of SubscriptionClient from subscriptions-transport-wscache (Required if ssrMode is true, otherwise optional): Object with the following methods:
cache.get(key)cache.set(key, data)cache.delete(key)cache.clear()cache.keys()getInitialState()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 passedheaders: Object, e.g. { 'My-Header': 'hello' }logErrors: Boolean - defaults to trueonError({ operation, result }): Custom error handler
operation: Object with query, variables and operationNameresult: Object containing data and error object that contains fetchError, httpError and graphqlErrorsclient methodsclient.setHeader(key, value): Updates client.headers adding the new header to the existing headersclient.setHeaders(headers): Replaces client.headersclient.removeHeader(key): Updates client.headers removing the header if it existsclient.logErrorResult({ operation, result }): Default error logger; useful if you'd like to use it inside your custom onError handlerrequest(operation, options): Make a request to your GraphQL server; returning a Promise
operation: Object with query, variables and operationNameoptions.fetchOptionsOverrides: Object containing additional fetch options to be added to the default ones passed to new GraphQLClient(config)ClientContextClientContext 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)
}
useQueryUsage:
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 stringoptions: 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 resultskipCache: 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 automaticallyssr: Boolean - defaults to true. Set to false 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 replace data in useQuery return value
previousData: Previous GraphQL query or updateData resultdata: New GraphQL query resultclient: GraphQLClient - If a GraphQLClient is explicitly passed as an option, then it will be used instead of the client from the ClientContext.useQuery return valueconst { loading, error, data, refetch, cacheHit } = useQuery(QUERY)
loading: Boolean - true if the query is in flightdata: Object - the result of your GraphQL queryrefetch(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 debuggingerror: Object - Set if at least one of the following errors has occurred and contains:
fetchError: Object - Set if an error occurred during the fetch callhttpError: Object - Set if an error response was returned from the servergraphQLErrors: Array - Populated if any errors occurred whilst resolving the queryuseManualQueryUse 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>
)
}
useMutationMutations 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 the ClientContext.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 dataerror: Error - the errorloading: Boolean - true if it is still loadingcacheHit: Boolean - true if the result was cacheduseSubscriptionTo use subscription you need to use subscriptions-transport-ws
API
useSubscription(operation, callback)
operation: Object - The GraphQL operation 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 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 povider. 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'
const client = new GraphQLClient({
url: 'http://localhost:8000/graphql',
subscriptionClient: new SubscriptionClient('ws://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 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>
)
}
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>
)
}
const client = new GraphQLClient({
url: 'https://domain.com/graphql',
fetch: require('node-fetch'),
FormData: require('formdata-node')
})
const uploadPostPictureMutation = `
mutation UploadPostPicture($picture: Upload!) {
uploadPostPicture(picture: $picture) {
id
pictureUrl
}
}
`
const { data, error } = await client.request({
query: uploadPostPictureMutation,
variables: { picture: createReadStream('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 the to the graphql-hooks client context by using the 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 success 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 ➡️ urlfetchOptionsonError - the function signature is slightly differentheadersfetchcache- 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 of gql and pass your queries as strings.variables ➡️ useQuery(query, { variables })ssr ➡️ useQuery(query, { ssr })cache-first: This the default behaviour of graphql-hookscache-and-network: The refetch function provides this behaviour 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 the error to be truthy. See useQuery for more details.pollIntervalnotifyOnNetworkStatusChangeskiponCompleted: Similar ability if using useManualQueryonError: Similar ability if using useManualQuerypartialRefetch- <Query query={gql`...`}>
- {(props) => {}}
- </Query>
+ const state = useQuery(`...`)
props.loading ➡️ const { loading } = useQuery('...')props.error ➡️ const { error } = useQuery('...'): The error value from useQuery is Boolean the details of the error can be found in either:
state.fetchErrorstate.httpErrorstate.graphQLErrorsprops.refetch ️➡️ const { refetch } = useQuery('...')props.updateData(prevResult, options) ️➡️ state.updateData(prevResult, newResult)Not yet supported
props.networkStatusprops.startPollingprops.stopPollingprops.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 in gqlvariables ➡️️ useMutation(mutation, { variables }) or mutateFn({ variables })ignoreResults ➡️️️️ const [mutateFn] = useMutation(mutation)onCompleted ➡️ ️mutateFn().then(onCompleted)onError ➡️ mutateFn().then(({ error }) => {...})Not yet supported
update: Coming soon #52optimisticResponserefetchQueriesawaitRefetchQueriescontext- <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.fetchErrorstate.httpErrorstate.graphQLErrorsclient ️➡️️ const client = useContext(ClientContext) see ClientContextNot yet supported
calledIt 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)
})
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
FAQs
Graphql Hooks
The npm package graphql-hooks receives a total of 17,127 weekly downloads. As such, graphql-hooks popularity was classified as popular.
We found that graphql-hooks demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
vlt's new "reproduce" tool verifies npm packages against their source code, outperforming traditional provenance adoption in the JavaScript ecosystem.
Research
Security News
Socket researchers uncovered a malicious PyPI package exploiting Deezer’s API to enable coordinated music piracy through API abuse and C2 server control.
Research
The Socket Research Team discovered a malicious npm package, '@ton-wallet/create', stealing cryptocurrency wallet keys from developers and users in the TON ecosystem.
