Querying Data in Components with the useStaticQuery Hook
Gatsby v2.1.0 introduces useStaticQuery
, a new Gatsby feature that provides the ability to use a React Hook to query with GraphQL at build time.
Just like the StaticQuery component, it allows your React components to retrieve data via a GraphQL query that will be parsed, evaluated, and injected into the component. However, useStaticQuery
is a hook rather than a component that takes a render prop!
In this guide, you will walk through an example using useStaticQuery
. If you’re not familiar with static queries in Gatsby, you might want to check out the difference between a static query and a page query.
How to use useStaticQuery in components
💡 You’ll need React and ReactDOM 16.8.0 or later to use
useStaticQuery
.📦
npm install react@^16.8.0 react-dom@^16.8.0
useStaticQuery
is a React Hook. All the Rules of Hooks apply.
It takes your GraphQL query and returns the requested data. That’s it!
Basic example
Let’s create a Header
component that queries for the site title from gatsby-config.js
:
Composing custom useStaticQuery
hooks
One of the most compelling features of hooks is the ability to compose and re-use these blocks of functionality. useStaticQuery
is a hook. Therefore, using useStaticQuery
allows us to compose and re-use blocks of reusable functionality. Perfect!
A classic example is to create a useSiteMetadata
hook which will provide the siteMetadata
to be re-used in any component. It looks something like:
Then import your newly created hook, like so:
Known Limitations
useStaticQuery
does not accept variables (hence the name “static”), but can be used in any component, including pages- Because of how queries currently work in Gatsby, we support only a single instance of
useStaticQuery
in a file