How To Handle Images with GraphQL and the Gatsby Image API

The author selected /dev/color to receive a donation as part of the Write for DOnations program.

Introduction

Handling images plays a pivotal role in building websites, but also can be challenging to deal with. Unoptimized images slow down websites, and many images that might look appropriate on a desktop are hard to scale down to a mobile device. Visually manipulating an image can also be tedious and difficult to maintain.

All of these problems in isolation are not a big issue. The main problem is when you have to keep track of all of these rules and image-scaling techniques. When it comes to Gatsby.js projects, this is where the Gatsby Image API comes in handy. By using GraphQL queries, you can use the Gatsby Image API to take care of image compression, make an image responsive, and even handle basic image styling.

In this tutorial, you are going to compress, transform, and style images using the Gatsby Image API and GraphQL queries.

Prerequisites

• Node.js version 10.16.0 installed on your computer. To install this on macOS or Ubuntu 18.04, follow the steps in How to Install Node.js and Create a Local Development Environment on macOS or the Installing Using a PPA section of How To Install Node.js on Ubuntu 18.04.

• Gatsby.js and the Gatsby CLI tool installed. You can find out how to install this in the How To Set Up Your First Gatsby Website tutorial.

• It will help to be comfortable with building websites with HTML, and styling with CSS, which you can learn more about in the How To Build a Website with CSS series.

• An understanding of JavaScript will be useful. You can learn more about JavaScript in our How To Code in JavaScript series. Although Gatsby uses React, you don’t need to know React in order to get started, but it would be helpful to be familiar with the basic concepts. You can learn React with this series.

Step 1 — Setting Up a New Gatsby Project

In this first step, you are going to set up a new Gatsby project and familiarize yourself with the key image plugins that you’ll use throughout this tutorial. You will also download and set up an image to optimize throughout the tutorial.

First, use the CLI tool to start a new project named gatsby-image-project:

gatsby new gatsby-image-project https://github.com/gatsbyjs/gatsby-starter-default

This creates a new website from the starter template in the gatsby-starter-default GitHub repository from Gatsby.

Once the project is created, move into the new project directory:

cd gatsby-image-project

Next, open up the index.js file in a text editor of your choice:

nano src/pages/index.js

Delete all of the code between the layout wrapper component so that your file is the same as the following:

import React from "react"
import { Link } from "gatsby"

import Layout from "../components/layout"
import Image from "../components/image"
import SEO from "../components/seo"

const IndexPage = () => (
  <Layout>
  </Layout>
)

export default IndexPage

Next, replace the deleted code with the following highlighted JSX, which adds some HTML elements to the website:

import React from "react"
import { Link } from "gatsby"

import Layout from "../components/layout"
import Image from "../components/image"
import SEO from "../components/seo"

const IndexPage = () => (
    <Layout>
      <div className="layout">
        <Image className="left-image"/>
        <h2>Hello</h2>
        <p>Welcome to my humble site</p>
        <p>All of our shirts are on sale!</p>
        <button className="shop-button">Shop</button>
      </div>
    </Layout>
)

export default IndexPage

The Gatsby Image API will provide your new test image to the Image element in a later step. With this, you now have HTML to experiment with.

Later in the tutorial, you’ll revisit the index.js page. For now, save and exit the file.

The next file to open is gatsby-config.js. In this file, you will find the plugins responsible for processing images.

Open up the file with the following:

nano gatsby-config.js

Once you have opened the gatsby-config file, locate the gatsby-plugin-sharp, gatsby-transformer-sharp, and gatsby-source-filesystem plugins:

module.exports = {
  siteMetadata: {
    title: `Gatsby Default Starter`,
    description: `Kick off your next, great Gatsby project with this default starter. This barebones starter ships with the main Gatsby configuration files you might need.`,
    author: `@gatsbyjs`,
  },
  plugins: [
    `gatsby-plugin-react-helmet`,
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `images`,
        path: `${__dirname}/src/images`,
      },
    },
    `gatsby-transformer-sharp`,
    `gatsby-plugin-sharp`,
    {
      resolve: `gatsby-plugin-manifest`,
      options: {
        name: `gatsby-starter-default`,
        short_name: `starter`,
        start_url: `/`,
        background_color: `#663399`,
        theme_color: `#663399`,
        display: `minimal-ui`,
        icon: `src/images/gatsby-icon.png`, // This path is relative to the root of the site.
      },
    },
    // this (optional) plugin enables Progressive Web App + Offline functionality
    // To learn more, visit: https://gatsby.dev/offline
    // `gatsby-plugin-offline`,
  ],
}

These plugins are as follows:

• gatsby-plugin-sharp: Sharp is an image optimization library that Gatsby uses to process images. The gatsby-plugin-sharp provides a bridge between Sharp and Gatsby.

• gatsby-transformer-sharp: This plugin performs image transformations, such as resizing, compressing, and changing background color.

• gatsby-source-filesystem: This plugin allows you to source data from your filesystem into your application. In this case, it enables GraphQL to query images.

Now that you have an idea of which plugins are used to process images, close the file.

Next, add an image to your application to optimize, edit, and style later. In this tutorial, you are going to download an image from the Unsplash stock image website. Navigate to this picture of clothes on Unsplash in a browser and download the angela-bailey-jlo7Bf4tUoY-unsplash.jpg image into the /images folder of your Gatsby project. The image must be located in the right directory in order to query the image with GraphQL and transform it using Gatsby’s Image API.

Alternatively, you can download the image from the command line. First, move to the images directory:

cd src/images

Next, execute the following command:

curl -sL https://images.unsplash.com/photo-1556905055-8f358a7a47b2 -o angela-bailey-jlo7Bf4tUoY-unsplash.jpg

This will use curl to download the image and output the file as angela-bailey-jlo7Bf4tUoY-unsplash.jpg.

In this section, you set up your Gatsby project to use Gatsby’s Image API. You explored the Gatsby configuration file to find gatsby-plugin-sharp, gatsby-transform-sharp, and gatsby-source-filesystem, which work together to optimize images. In the next step, you will test out querying and optimizing your image using GraphiQL, the GraphQL integrated development environment (IDE).

Step 2 — Querying Images with GraphQL

You are now going to query your new image using GraphQL. GraphQL is a query language for obtaining information from an API. It is also the data layer of Gatsby.

First, return to the root of your Gatsby project, then start the development server:

gatsby develop

After your site finishes building, you will receive the following output:

Output
...
success open and validate gatsby-configs - 0.081s
success load plugins - 4.537s
success onPreInit - 0.070s
success initialize cache - 0.034s
success copy gatsby files - 0.320s
success onPreBootstrap - 0.177s
success createSchemaCustomization - 0.050s
success Checking for changed pages - 0.003s
success source and transform nodes - 0.264s
success building schema - 0.599s
info Total nodes: 35, SitePage nodes: 1 (use --verbose for breakdown)
success createPages - 0.057s
success Checking for changed pages - 0.005s
success createPagesStatefully - 0.188s
success update schema - 0.046s
success write out redirect data - 0.006s
success Build manifest and related icons - 0.456s
success onPostBootstrap - 0.465s
info bootstrap finished - 19.515s
success onPreExtractQueries - 0.003s
success extract queries from components - 0.932s
success write out requires - 0.029s
success run page queries - 0.039s - 1/1 25.97/s
⠀
You can now view gatsby-starter-default in the browser.
⠀
  http://localhost:8000/
⠀
View GraphiQL, an in-browser IDE, to explore your site's data and schema
⠀
  http://localhost:8000/___graphql
⠀
Note that the development build is not optimized.
To create a production build, use gatsby build
⠀
warn ESLintError: 
/your_filepath/gatsby-image-project/src/pages/index.js
  2:10  warning  'Link' is defined but never used  no-unused-vars
  6:8   warning  'SEO' is defined but never used   no-unused-vars

✖ 2 problems (0 errors, 2 warnings)

success Building development bundle - 10.814s

This output contains two links. The first link, https://localhost:8000/, is where you can find your local development site. The second link, http://localhost:8000/___graphql, is the location of GraphiQL. GraphiQL is an integrated development editor (IDE) that allows you to make queries in the browser. This is a useful tool that helps you experiment and make data queries before you add them to your codebase. GraphiQL only works when you are running the development server.

With the help of GraphiQL, you can try out queries to retrieve your newly downloaded image. Open your browser and enter the GraphiQL URL http://localhost:8000/___graphql into the address bar. The browser will display the GraphiQL interface:

GraphiQL is split into three sections. To the far left is the Explorer, where you can find the fields that you are able to access via GraphQL. In the middle of the IDE is the sandbox where you make queries. Finally, to the far right you can find GraphQL’s documentation.

Your first goal is to query the angela-bailey-jlo7Bf4tUoY-unsplash.jpg image. Since the image is located in the local filesystem, you choose file in the Explorer box. This will show a dropdown menu of subdirectories. You will search for the image file by relative path, so select on relativePath. relativePath reveals another set of subfolders. You will enter the exact path of the image, so choose the eq for “equals”. Inside the quotes enter the path of the image angela-bailey-jlo7Bf4tUoY-unsplash.jpg.

Now you are set to try out your first image manipulation. Your original image is 1920 by 1280 pixels. That is too big for your landing page, and it would help to make the image responsive. Normally, you would have to hard code the width into CSS and add media queries to make the image responsive. Gatsby’s Image API does all of that work for you, without you needing to write extra CSS.

Select childImageSharp in the Explorer box, which transforms the image under the hood. Make sure to choose this from the top-level menu, not from under file. Choose fluid from the next dropdown. A fluid image stretches to fill its container. In the dropdown options for fluid, check maxWidth and enter the 750.

The blue values just below the purple querying parameters are the different values you can return. Choose src and srcSet to return the location of the original and transformed image. Then click the play button to view the results:

After selecting the parameters, GraphiQL builds the following query:

query MyQuery {
  file(relativePath: {eq: "angela-bailey-jlo7Bf4tUoY-unsplash.jpg"}) {
    childImageSharp {
      fluid(maxWidth: 750) {
        src
        srcSet
      }
    }
  }
}

In the box on the right of the GraphiQL interface, you will find the return values. This will show:

• src: Location of the image after processing.

• srcSet: Same image set to a different size. This feature comes in handy if you want your images to be responsive.

You do not have to choose fluid in your query; you also have the option to choose fix. A fixed image creates responsive images 1x, 1.5x, and 2x pixel densities using the <picture> element. The following is an example of a fixed query:

query MyQuery {
  file(relativePath: {eq: "angela-bailey-jlo7Bf4tUoY-unsplash.jpg"}) {
    childImageSharp {
      fixed(cropFocus: CENTER) {
        src
        srcSet
      }
    }
  }
}

This query will return the following:

{
  "data": {
    "file": {
      "childImageSharp": {
        "fixed": {
          "src": "/static/8e3a47b77ddf6636755d7be661d7b019/0ad16/angela-bailey-jlo7Bf4tUoY-unsplash.jpg",
          "srcSet": "/static/8e3a47b77ddf6636755d7be661d7b019/0ad16/angela-bailey-jlo7Bf4tUoY-unsplash.jpg 1x,\n/static/8e3a47b77ddf6636755d7be661d7b019/44157/angela-bailey-jlo7Bf4tUoY-unsplash.jpg 1.5x,\n/static/8e3a47b77ddf6636755d7be661d7b019/7fddd/angela-bailey-jlo7Bf4tUoY-unsplash.jpg 2x"
        }
      }
    }
  },
  "extensions": {}
}

In this query you have a fixed version of the image, with the crop focus set to center. Your return value is the location of the image and a set of different image sizes (1x, 1.5x, 2x respectively).

Now that you have tested out the GraphQL query using GraphiQL and the childImageSharp node, you will next add the queried image to a template and further optimize it using Gatsby’s Image API.

Step 3 — Optimizing Your Image’s Performance for the Web

In this section you are going to transfer your GraphQL image to the index.js page of your project and perform more image optimizations.

From your terminal in the root of your Gatsby project, open the image component in your favorite text editor:

nano src/components/image.js

Now, use the query that you tried out in the GraphiQL interface. Delete "gatsby-astronaut.png" and replace it with "angela-bailey-jlo7Bf4tUoY-unsplash.jpg". Also replace maxWidth: 300 with maxWidth: 750:

import React from "react"
import { useStaticQuery, graphql } from "gatsby"
import Img from "gatsby-image"

/*
 * This component is built using `gatsby-image` to automatically serve optimized
 * images with lazy loading and reduced file sizes. The image is loaded using a
 * `useStaticQuery`, which allows us to load the image from directly within this
 * component, rather than having to pass the image data down from pages.
 *
 * For more information, see the docs:
 * - `gatsby-image`: https://gatsby.dev/gatsby-image
 * - `useStaticQuery`: https://www.gatsbyjs.com/docs/use-static-query/
 */

const Image = () => {
  const data = useStaticQuery(graphql`
    query {
      placeholderImage: file(relativePath: { eq: "angela-bailey-jlo7Bf4tUoY-unsplash.jpg" }) {
        childImageSharp {
          fluid(maxWidth: 750) {
            ...GatsbyImageSharpFluid
          }
        }
      }
    }
  `)

  if (!data?.placeholderImage?.childImageSharp?.fluid) {
    return <div>Picture not found</div>
  }

  return <Img fluid={data.placeholderImage.childImageSharp.fluid} />
}

export default Image

...GatsbyImageSharpFluid is a GraphQL fragment. This syntax allows you to obtain all of the different return values for childImageSharp and fluid. You will use this as the return value instead of src and srcSet.

In the image.js file, after the GraphQL query there is an if statement:

...
  if (!data?.placeholderImage?.childImageSharp?.fluid) {
    return <div>Picture not found</div>
  }

  return <Img fluid={data.placeholderImage.childImageSharp.fluid} />
}

export default Image

placeholderimage is the alias that is given in the query and returned in <Img fluid={data.placeholderImage.childImageSharp.fluid} />. In GraphQL you are able to name your queries. In the conditional statement, if you don’t have an image, then the words Picture not found will appear on the landing page.

Save and close this file.

Once you build your Gatsby site, the image will be processed and optimized by the Gatsby Image API. This will decrease the size of the image file to decrease loading time for your site. To test this out, navigate to the images directory to find the original file size:

cd src/images

Now list out the files with the following command:

ls -sh

The -sh flag will show you the memory size of the files in a human-readable format. You will receive the following output:

Output
total 5.0M
4.8M angela-bailey-jlo7Bf4tUoY-unsplash.jpg  164K gatsby-astronaut.png   24K gatsby-icon.png

Without any optimization, the image is 4.8M. Now you will look at how big the image is after you’ve used Gatsby’s Image API.

Navigate to the root of your project and start the development server:

gatsby develop

Once the development server has started, place the local address into the browser. Once the site has loaded, right-click the image and select Inspect.

Now navigate to the Network tab of your browser’s developer tools. This tutorial will use Google Chrome DevTools:

Your image went from 4.8 MB to 68.4 kB. That is significantly smaller than if you hadn’t used the Gatsby Image API.

Keep developer tools open and head over to the Elements tab. Hover over the image. You will find the HTML element <picture>...</picture> and its child <source>...</source>:

In the source tag, you can find the srcSet attribute (the same one you queried for in GraphQL). You will also find that the different heights and widths of the image were automatically generated. These different images ensure that angela-bailey-jlo7Bf4tUoY-unsplash.jpg is fluid, without needing to change CSS.

In this section you used the GraphQL Image query in your Gatsby template. You also optimized angela-bailey-jlo7Bf4tUoY-unsplash.jpg without having to write extra CSS.

In the next section, you will visually transform the image by using childSharpImage.

Step 4 — Styling Your Image with childSharpImage

In this section, you will transform the look of angela-bailey-jlo7Bf4tUoY-unsplash.jpg with the help of childSharpImage. To test this, you will change your image to grayscale.

Open image.js in a text editor:

nano src/components/image.js

Go into your placeholderImage GraphQL query and inside of fluid set grayscale to true:

import React from "react"
import { useStaticQuery, graphql } from "gatsby"
import Img from "gatsby-image"

/*
 * This component is built using `gatsby-image` to automatically serve optimized
 * images with lazy loading and reduced file sizes. The image is loaded using a
 * `useStaticQuery`, which allows us to load the image from directly within this
 * component, rather than having to pass the image data down from pages.
 *
 * For more information, see the docs:
 * - `gatsby-image`: https://gatsby.dev/gatsby-image
 * - `useStaticQuery`: https://www.gatsbyjs.com/docs/use-static-query/
 */

const Image = () => {
  const data = useStaticQuery(graphql`
    query {
      placeholderImage: file(relativePath: { eq: "angela-bailey-jlo7Bf4tUoY-unsplash.jpg" }) {
        childImageSharp {
          fluid(
            maxWidth: 750
            grayscale: true
            ) {
            ...GatsbyImageSharpFluid
          }
        }
      }
    }
  `)

  if (!data?.placeholderImage?.childImageSharp?.fluid) {
    return <div>Picture not found</div>
  }

  return <Img fluid={data.placeholderImage.childImageSharp.fluid} tabIndex='0' />
}

export default Image

Save and close the file.

Go back to your terminal and restart the server. You will find your image changed using childImageSharp, without writing and maintaining unnecessary CSS:

Grayscale is just one of the many ways you can process your image using childImageSharp. Go to Gatsby’s documentation if you are curious about the other childImageSharp props.

In this section you implemented grayscale by using childImageSharp. With this knowledge, you can perform many more image manipulations by leveraging the Gatsby Image API.

Conclusion

In this tutorial, you set your Gatsby project up to use the Gatsby Image API, query your Image using GraphQL, optimize your image’s performance, and style your image using childImageSharp. If you would like to learn more about Gatsby, check out the official Gatsby documentation.