StaticQuery in Gatsby v2

2 min read

Part of a series on Gatsby v2

You've heard about StaticQuery as part of Gatsby v2. GraphQL everywhere. Sounds great, but how does it work?

tl;dr - Wrap any component in StaticQuery and pass two props query and render. These queries do not get any data about the current page, they're static for the entire build.

What is StaticQuery?

In Gatsby v1 there was only 2 places you could use GraphQL. Layouts and pages. Layouts have disappeared in Gatsby v2. Pages still use GraphQL.

Imagine you want to pass the title from you gatsby-config.js file into a component. In Gatsby v1 you would have to get that data via the layout or the page. With StaticQuery, you can get that data anywhere.

Or put another way, StaticQuery lets you write GraphQL queries which are parsed once during the build process. Think of it like this:

  • Gatsby boots and loads all your files
  • All GraphQL queries are extracted
  • All StaticQuery instances are parsed, their queries run, and the data bound to their components
  • All pages are built and page specific GraphQL queries run per page

Where to use StaticQuery?

Short answer, anywhere. You just import and it works. A few examples where StaticQuery would be useful:

  • Passing the global site metadata to Helmet
  • Showing a list of the 5 most recent posts
  • Displaying the 5 best selling products in a store


Enough theory, time to dive into some code. Here's the example from the StaticQuery docs:

import React from "react"
import { StaticQuery, graphql } from "gatsby"

const Header = () => (
      query {
        site {
          siteMetadata {
    render={data => (

export default Header

Let's unpack that a bit.

  • First we import StaticQuery from gatsby. It's a named export.
  • Then we render <StaticQuery just like any other React component
  • It accepts two props, query and render
  • The query prop takes a graphql template string

    • NOTE: graphql must be imported from gatsby in Gatsby v2
  • The render prop takes a function

    • That function accepts a single argument data
    • The data argument is filled with the result of the GraphQL query
    • We render an h1 tag containing

NOTE: The data argument passed to the render function is not props, it is only the data. It's more like, and it should not be destructured like ({ data }) => ....

If you haven't seen it before, the siteMetadata object is filled from gatsby-config.js. It's a convenient way to pass config values into your Gatsby site without hard coding them.

Rating: 3.8 - 5 Reviews
Is this post useful to you? Please give us a rating!


Want regular updates on Gatsby and its awesomeness? Subscribe here. No spam, promise. Full details on privacy.

We use MailChimp as our marketing automation platform. By clicking "Submit" to submit this form, you acknowledge that the information you provide will be transferred to MailChimp for processing in accordance with their Privacy Policy and Terms.


If you'd like to share this post, here are some handy links to make that easier.

Post last updated: July 18, 2018


Feedback? A point to make? Express yourself via the comment form below.

Don't forget to check the captcha. Otherwise we won't receive your comment.

Be the first to post a comment on this post