Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ContactSign Up

Introducing useStaticQuery

Sidhartha Chatterjee
February 20th, 2019

React Hooks are cool. Besides simplifying your code and removing the need for a lot of boilerplate associated with classes in JavaScript (looking at you, this), they enable some serious shareability. They also make it possible to use state in functional components.

You can probably tell that we've been super excited about React Hooks. So when they finally landed in React 16.8, we figured it was time to give our very own StaticQuery component the hook treatment!

Say hello to useStaticQuery

useStaticQuery is a hook that takes a GraphQL query and returns your data. That's it.

No more Render Props necessary to use a Static Query

This simplifies accessing data in your components and also keeps your component tree shallow.

Let's quickly check out a basic example. Here's a typical Header component, first written using StaticQuery and then useStaticQuery.



Isn't that cleaner and more succinct?

Just like StaticQuery, when you build your site for production, Gatsby will parse and execute your queries in useStaticQuery and inject data in just the right place.

Where this gets even more powerful is the ability to create custom hooks that use useStaticQuery in them. Let's say you need to query for the site title several times in your app. Instead of a call to useStaticQuery in each component, you can extract it out to a custom hook like:

Now every time you need the site title, you can use this custom hook.

Isn't that neat?


And if there's a change to the structure of that data, you only need to change the query in one place!

We're really excited about this pattern and everything it enables. With our upcoming themes feature, a theme could even export custom hooks of its own. Users could access data using these without writing a single query.

Where can I get this?

The astute reader (Jacob is astute, be like Jacob) would've noticed that we stealthily released useStaticQuery last week.

To use useStaticQuery, update gatsby to v2.1.0 and react and react-dom to v16.8.0!

Known Limitations

Because of the way queries are currently parsed in Gatsby, useStaticQuery has one small limitation at the moment. You can only use one instance of useStaticQuery in a file. That's it! This doesn't mean your app can't have multiple uses, but rather that a single JavaScript file can only have one instance of useStaticQuery.

We're working on fixing this soon.

Next Steps

  • Check out the documentation
  • To see useStaticQuery in action (and for a really gentle introduction to Hooks in general), check out the livestream Jason Lengstorf and I did last week
  • Hit me up on Twitter for any questions!

We hope you enjoy using useStaticQuery in your Gatsby apps. Happy building!

Share on TwitterShare on LinkedInShare on FacebookShare via Email

Senior Software Engineer, core team @ GatsbyJS. Scuba diver.

Follow Sidhartha Chatterjee on Twitter

Tagged with releasesView all Tags

Talk to our team of Gatsby Experts to supercharge your website performance.

Contact Gatsby Now
© 2023 Gatsby, Inc.