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 just 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