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.
💡 You’ll need React and ReactDOM 16.8.0 or later to use
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!
Let’s create a
Header component that queries for the site title from
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 just import your newly created hook, like so:
useStaticQuerydoes 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
useStaticQueryin a file