Recipes: Working with Images

Access images as static resources, or automate the process of optimizing them through powerful plugins.

Import an image into a component with webpack

Images can be imported right into a JavaScript module with webpack. This process automatically minifies and copies the image to your site’s public folder, providing a dynamic image URL for you to pass to an HTML <img> element like a regular file path.

Video hosted on egghead.io.

Prerequisites

• A Gatsby Site with a .js file exporting a React component
• an image (.jpg, .png, .gif, .svg, etc.) in the src folder

Directions

1. Import your file from its path in the src folder:

2. In index.js, add an <img> tag with the src as the name of the import you used from webpack (in this case FiestaImg), and add an alt attribute describing the image:

3. Run gatsby develop to start the development server.
4. View your image in the browser: http://localhost:8000/

Additional resources

• Example repo importing an image with webpack
• More on all image techniques in Gatsby

Reference an image from the static folder

As an alternative to importing assets with webpack, the static folder allows access to content that gets automatically copied into the public folder when built.

This is an escape route for specific use cases, and other methods like importing with webpack are recommended to leverage optimizations made by Gatsby.

Video hosted on egghead.io.

Prerequisites

• A Gatsby Site with a .js file exporting a React component
• An image (.jpg, .png, .gif, .svg, etc.) in the static folder

Directions

1. Ensure that the image is in your static folder at the root of the project. Your project structure might look something like this:

2. In index.js, add an <img> tag with the src as the relative path of the file from the static folder, and add an alt attribute describing the image:

3. Run gatsby develop to start the development server.
4. View your image in the browser: http://localhost:8000/

Additional resources

• Example repo referencing an image from the static folder
• Using the Static Folder
• More on all image techniques in Gatsby

Optimizing and querying local images with gatsby-image

The gatsby-image plugin can relieve much of the pain associated with optimizing images in your site.

Gatsby will generate optimized resources which can be queried with GraphQL and passed into Gatsby’s image component. This takes care of the heavy lifting including creating several image sizes and loading them at the right time.

Prerequisites

• The gatsby-image, gatsby-transformer-sharp, and gatsby-plugin-sharp packages installed and added to the plugins array in gatsby-config
• Images sourced in your gatsby-config using a plugin like gatsby-source-filesystem

Directions

1. First, import Img from gatsby-image, as well as graphql and useStaticQuery from gatsby

2. Write a query to get image data, and pass the data into the <Img /> component:

Choose any of the following options or a combination of them.

a. a single image queried by its file path (Example: images/corgi.jpg)

b. using a GraphQL fragment, to query for the necessary fields more tersely

c. several images from a directory (Example: images/dogs) filtered by the extension and relativeDirectory fields, and then mapped into Img components

Note: This method can make it difficult to match images with alt text for accessibility. This example uses images with alt text included in the filename, like dog in a party hat.jpg.

d. an image of a fixed size using the fixed field instead of fluid

e. an image of a fixed size with a maxWidth

f. an image filling a fluid container with a max width (in pixels) and a higher quality (the default value is 50 i.e. 50%)

3. (Optional) Add inline styles to the <Img /> like you would to other components

4. (Optional) Force an image into a desired aspect ratio by overriding the aspectRatio field returned by the GraphQL query before it is passed into the <Img /> component

5. Run gatsby develop, to generate images from files in the filesystem (if not done already) and cache them

Additional resources

• Example repository illustrating these examples
• Gatsby Image API
• Using Gatsby Image
• More on working with images in Gatsby
• Free egghead.io videos explaining these steps

Optimizing and querying images in post frontmatter with gatsby-image

For use cases like a featured image in a blog post, you can still use gatsby-image. The Img component needs processed image data, which can come from a local (or remote) file, including from a URL in the frontmatter of a .md or .mdx file.

To inline images in markdown (using the ![]() syntax), consider using a plugin like gatsby-remark-images

Prerequisites

• The gatsby-image, gatsby-transformer-sharp, and gatsby-plugin-sharp packages installed and added to the plugins array in gatsby-config
• Images sourced in your gatsby-config using a plugin like gatsby-source-filesystem
• Markdown files sourced in your gatsby-config with image URLs in frontmatter
• Pages created from Markdown using createPages

Directions

1. Verify that the Markdown file has an image URL with a valid path to an image file in your project

2. Verify that a unique identifier (a slug in this example) is passed in context when createPages is called in gatsby-node.js, which will later be passed into a GraphQL query in the Layout component

3. Now, import Img from gatsby-image, and graphql from gatsby into the template component, write a pageQuery to get image data based on the passed in slug and pass that data to the <Img /> component:

4. Run gatsby develop, which will generate images for files sourced in the filesystem

Additional resources

• Example repository using this recipe
• Featured images with frontmatter
• Gatsby Image API
• Using Gatsby Image
• More on working with images in Gatsby