Chapter 5: Working with Images
In this chapter, you will master the art of adding images to your Gatsby site. First, we will learn a little about the history of images on the web, before understanding why importing images is not as easy you might think. We will then move on to creating images that progressively load in and are performant.
In this chapter, we will cover the following topics:
- Images on the web
- The StaticImage component
- The GatsbyImage component
- Overriding the gatsby-plugin-image defaults
- Sourcing images from CMS
Technical requirements
To complete this chapter, you will need to have completed Chapter 3, Sourcing and Querying Data (from Anywhere!).
The code for this chapter can be found at https://github.com/PacktPublishing/Elevating-React-Web-Development-with-Gatsby-4/tree/main/Chapter05.
Images on the web
When was the last time you visited a website without any images? You might be thinking that this is a hard question to answer. Images are a critical part of websites and our browsing experience. We use images for logos, products, profiles, and marketing to convey information, entice, or excite through a visual medium. While images are great for these use cases (and many more!), they are the single largest contributor to page size. According to the HTTP Archive (https://httparchive.org/), the median page size on desktops is 2,124 KB. Images make up 973 KB of this size, which is roughly 45% of the total page size.
As images are so integral to our browsing experience, we cannot do away with them. But when they account for so much of the page size, we should be doing everything in our power to ensure that they are optimized, accessible, and as performant as possible. Newer versions of browsers (including Chrome) have responsive image capabilities built into them. Instead of providing a single source for the image, the browser can accept a source set. The browser uses this set to load an image at a different size, depending on the size of the device. This ensures the browser never loads images that are too big for the space available. Another way in which developers can optimize images, specifically in React, is with lazy loading. Lazy loading is the process of deferring the load of your images until a later point in time. This could be after the initial load, or when they specifically become visible on the screen. Using this technique, you can improve your site's speed, better utilize a device's resources, and reduce a user's data consumption.
Images in Gatsby
Manually creating high-performance sites that contain lazy-loaded images is a project in itself. Luckily, Gatsby has a plugin that takes the pain away when you're generating responsive, optimized images – gatsby-plugin-image.
This plugin contains two React image components with specific features aimed at creating a better user experience when using images, both for the developer and the site visitor:
- Loads the correct image for the device viewing the site.
- Reduces cumulative layout shift by holding the position of the image while it is loading.
- Uses a lazy loading strategy to speed up the initial load time of your site.
- Has multiple options for placeholder images that appear while the image is loading. You can make the images blur up or use a traced Scalable Vector Graphics (SVG) of the image in its place.
- Supports new image formats such as WebP if the browser can support it.
In the next section, we will begin looking at the first of the two image components in this chapter – the StaticImage component.
The StaticImage component
StaticImage is best used when an image will always remain the same. It could be your site logo, which is the same across all pages, or a profile photo that you use at the end of blog posts, or a home page hero section, or anywhere else where the image is not required to be dynamic.
Unlike most React components, the StaticImage component has some limitations on how you can pass the props to it. It will not accept and use any of its parents' props. If you are looking for this functionality, you will want to use the GatsbyImage component.
To get an understanding of how we utilize the StaticImage component, we will implement an image on the hero of our home page:
- Create an assets folder next to your src folder. To keep things organized, it is good practice to keep images away from your source code. We will use the assets folder to house any visual assets.
- Create a folder within assets called images. We will use this folder to store the visual assets of the image type.
- Add an image to your images folder. The image file type must be in .png, .jpg, .jpeg, .webp, or .avif format.
- Install gatsby-plugin-image and its dependencies:
npm install gatsby-plugin-image gatsby-plugin-sharp
gatsby-source-filesystem
These dependencies spawn other node processes and may take a little longer to install compared to our previous installs.
- Update your gatsby-config.js file so that it includes the three new dependencies:
plugins: [
'gatsby-plugin-image',
'gatsby-plugin-sharp',
'gatsby-transformer-sharp',
// Other plugins
],
- Import the StaticImage component into your index.js file:
import { StaticImage } from "gatsby-plugin-image";
- Use the StaticImage component within the render on the page:
<StaticImage
src="../../assets/images/sample-photo.jpeg"
/>
The src prop should be the relative path to the image from the current file, not the root directory.
- Modify the image that's rendered via props:
<StaticImage
src="../../assets/images/sample-photo.jpeg"
alt="A man smiling"
placeholder="tracedSVG"
layout="fixed"
width={400}
height={600}
/>
Let's look at these props in detail:
- src: This prop is the relative path to the image from the current file.
- alt: As you would with a normal img tag, be sure to include an alt prop with text describing the image so that your image remains accessible.
- Placeholder: This prop tells the component what to display while the image is loading. Here, we have set it to tracedSVG, which uses a placeholder SVG (created by tracing the image) to fill the gap where the image will load in, but also gives the user a sense of the shape of whatever is in the photo. Other options include blurred, dominantColor, and none.
- layout: This prop determines the size of images that are produced as the output by the plugin and their resizing. Here, we have set it to fixed – this suggests that the image will be at a consistent size when it renders. Other layout options include constrained, which takes a maximum height or width and can scale down, and fullWidth, which will also resize to fit the container but is not restricted to the maximum height or width.
- width and height: We can use these props to specify the width and height of the image.
Tip
StaticImage can also take a remote source as its src prop. Any images that are specified as URLs will be downloaded at build time and then resized. Using remote images instead of local images is a great way to keep your repository small, but it should also be remembered that Gatsby does not know when that image changes if it is outside of your repository. If the image is changed on the remote server, it will only update when you rebuild your project.
Now that we understand how to utilize the StaticImage component, let's turn our attention to the other half of gatsby-plugin-image and learn about the GatsbyImage component.
The GatsbyImage component
If ever you need to use dynamic images, such as those embedded in your Markdown content, then you can use the GatsbyImage component.
Let's add hero images to our Markdown/MDX blog posts using the GatsbyImage component:
- Install the gatsby-transformer-sharp npm package:
npm install gatsby-transformer-sharp
- Add some images to assets/images that you would like to use as covers for your blog posts – one per blog post.
- Update your Gatsby-config.js file so that it includes your assets source:
{
resolve: 'gatsby-source-filesystem',
options: {
path: '${__dirname}/assets/images',
},
},
Unlike StaticImage, GatsbyImage requires that images are ingested into our data layer. We can use the gatsby-source-filesystem plugin to achieve this, but by giving it the path to our images.
- For each blog post, modify the post file's frontmatter so that it includes a hero key that contains the relative path to the image:
---
type: Blog
title: My First Hackathon Experience
desc: This post is all about my learnings from my
first hackathon experience in London.
date: 2020-06-20
hero: ../../assets/images/cover-1.jpeg
tags: [hackathon, webdev, ux]
---
Here, you can see an updated example of the placeholder Markdown with a hero key added. Be sure to replace the relative path in this example with the one to your image.
- Add the GatsbyImage component and the getImage function as imports, at the top of the src/templates/blog-page.js file:
import { GatsbyImage, getImage } from "gatsby-plugin-
image";
- Modify the file's page query to reference the new images:
export const pageQuery = graphql'
query($slug: String!) {
blogpost: markdownRemark(fields: { slug: { eq:
$slug } }) {
frontmatter {
date
title
tags
hero {
childImageSharp {
gatsbyImageData(
width: 600
height: 400
placeholder: BLURRED
)
}
}
}
html
}
}
';
You may notice that the data that's passed to the gatsbyImageData function looks very similar to the props of the StaticImage component that we saw in Step 8 of the previous section. In this instance, we are using the BLURRED placeholder for the image, which uses a blurred, lower-resolution version of the image in place of the original image while it is loading. We are now able to retrieve the hero data from the component as it is included in the page query.
- Use the new data within the data prop to get the image within the component:
const {
blogpost: {
frontmatter: { date, tags, title, hero },
html,
},
} = data;
const heroImage = getImage(hero)
First, retrieve hero from the data prop, and then use the getImage utility from gatsby-plugin-image to retrieve the image data that's required to render it and assign it to a const.
- Render your image within your return statement:
<GatsbyImage image={heroImage} alt="Your alt text" />
Use the const defined in Step 7 to render the image within a GatsbyImage component. Be sure to provide it with alt text to keep your image accessible – you could provide this via frontmatter as well if you wish.
- Start or restart your development server and admire your hard work. Navigate to one of the blog posts and you should see your image blur in gracefully.
Further Exercise
We've learned how to add images to our blog pages, so why not use what you have learned to add a smaller version of the same image to the blog preview page? An implementation can be found in this book's GitHub repository (https://github.com/PacktPublishing/Elevating-React-Web-Development-with-Gatsby-3/tree/main/Chapter05) if you want to see how it can be achieved.
You might find yourself adding the same configuration to your images across the whole site. Let's find out how we can use the defaults to keep our code in Don't Repeat Yourself (DRY) form.
Overriding the gatsby-plugin-image defaults
To create a consistent look and feel, you may have included the same props with many instances of the two image components. Keeping these image components updated can be a monotonous task if your site is image-heavy. Instead, you could configure the defaults within the options of gatsby-plugin-sharp:
{
resolve: 'gatsby-plugin-sharp',
options: {
defaults: {
formats: ['auto', 'webp'],
placeholder: 'blurred'
quality: 70
breakpoints: [300…]
backgroundColor: 'transparent'
tracedSVGOptions: {}
blurredOptions: {}
jpgOptions: {}
pngOptions: {}
webpOptions: {}
avifOptions: {}
}
}
},
Let's look at each of these options in detail:
- formats: The file formats generated by the plugin.
- placeholder: Overrides the style of the temporary image.
- quality: The default image quality that's created.
- breakpoints: The widths to use for full-width images. It will never create an image with a width that's longer than the source.
- backgroundColor: The default background color of the images.
- tracedSVGOptions and blurredOptions: The default options to use for placeholder image types in the case that these are different from the global defaults.
- jpgOptions, pngOptions, webpOptions, and avifOptions: The default options to use for image types in the case that these are different from the global defaults.
We now have a good understanding of the gatsby-plugin-image package. There are, however, some important niches to using this package with other sources such as Content Management Systems (CMSes) – let's take a look.
Sourcing images from CMS
It is not always practical to store images within your repository. You may want someone other than yourself to be able to update or add images to your site without you needing to change the code. In these cases, serving images via CMS is preferable. It's still important that we use the Gatsby image plugin as we want our images to be performant, regardless of the source. To understand how we would integrate images via CMS, let's use an example. Let's add a profile image to our about page using gatsby-plugin-image and a CMS.
Important Note
Due to the vast number of headless CMSes in the market, we will continue to focus on the two mentioned in the Sourcing data from a Headless CMS section of Chapter 3, Sourcing and Querying Data (from Anywhere!): GraphCMS and Prismic.
Both of the following sections will assume you have already installed the CMS's dependencies and integrated the CMS via your gatsby-config.js file. Please only implement one of the following.
Sourcing images from GraphCMS
By making some small modifications to our configuration and queries, we can ensure that we can source images from GraphCMS that utilize gatsby-plugin-image and load in on the site in the same way as those that are locally sourced:
- Navigate to the GraphCMS website (graphcms.com) and log in.
- Navigate to your project's assets and click the upload button.
- Drag and drop a local image you wish to use onto the page. Be sure to take note of the file's name as we will need it later.
- Publish the asset.
- Modify your gatsby-source-graphcms plugin:
{
resolve: 'gatsby-source-graphcms',
options: {
endpoint: process.env.GRAPHCMS_ENDPOINT,
downloadLocalImages: true,
},
},
By modifying your gatsby-source-graphcms plugin's options to include the downloadLocalImages option, the plugin will download and cache the CMS's image assets within your Gatsby project.
- Modify your about page's query so that it includes the graphCmsAsset source:
export const query = graphql'
{
markdownRemark(frontmatter: { type: { eq: "bio" } }) {
html
}
graphCmsAsset(fileName: { eq: "profile.jpeg" }) {
localFile {
childImageSharp {
gatsbyImageData(layout: FULL_WIDTH)
}
}
}
}
';
As with the local queries we looked at in the The GatsbyImage component section, we are using gatsbyImageData within our query and can make use of any of the configuration options that it supports. Here, we are specifying that the image should be full width.
- Add the GatsbyImage component and the getImage function as imports at the top of the src/pages/about.js file:
import { GatsbyImage, getImage } from "gatsby-plugin-
image";
- Use the new data within the data prop to get the image within the component:
const {
markdownRemark: { html },
graphCmsAsset: { localFile },
} = data;
const profileImage = getImage(localFile);
First, retrieve graphCmsAsset from the data prop and then use the getImage utility from gatsby-plugin-image to retrieve the image data that's required to render it. Finally, assign it to a const called profileImage.
- Render your image within your return statement:
return (
<Layout>
<div className="max-w-5xl mx-auto py-16 lg:py-24
text-center">
<GatsbyImage
image={profileImage}
alt="Your alt text"
className="mx-auto max-w-sm"
/>
<div dangerouslySetInnerHTML={{ __html: html
}}></div>
</div>
</Layout>
);
Use the const parameter that we defined in Step 8 to render the image within a GatsbyImage component. Be sure to provide it with alt text to keep your image accessible – you could provide this via frontmatter as well if you wish.
- Restart your development server and admire your hard work by navigating to your about page.
Now that we understand how we can source images within GraphCMS, let's turn our attention to how the same can be achieved in Prismic.
Sourcing images from Prismic
With a few simple changes to our configuration and queries, we can source images from Prismic utilizing gatsby-plugin-image and load them in on the site in the same way as local images:
- Navigate to Prismic's website (prismic.io) and log in. Select your existing repository.
- Navigate to the CustomTypes tab, click the Create new button, and select Single Type. Name your type Profile and submit it.
- Using the build-mode sidebar (on the right), drag an image component into the type.
- Name your field photo; the corresponding API ID should populate on its own. Click OK to confirm this. If you've done this correctly, your profile type should look as follows:
Figure 5.1 – Prismic profile type
- Save the document.
- Navigate to the JSON editor and copy its contents to a new file called profile.json within your src/schemas folder.
- Navigate to the Documents tab and click the Create new button. If Prismic has not automatically opened your new type, select Profile. Using the interface, upload a new image into the document in the photo field.
- Save and publish the new document. We now have everything set up in the CMS and can return to our Gatsby project.
- Update your gatsby-source-prismic configuration within your gatsby-config.js file:
{
resolve: "gatsby-source-prismic",
options: {
repositoryName: "elevating-gatsby",
schemas: {
icebreaker:
require("./src/schemas/icebreaker.json"),
profile:
require("./src/schemas/profile.json"),
},
shouldDownloadFiles: () => true,
},
},
Add the new scheme to schemas that we added in Step 6. We will also add the shouldDownloadFiles option. This is a function that determines whether to download images. In our case, we always want it to download images so that we can use gatsby-plugin-image, and therefore set the function to always return true.
- Add the GatsbyImage component and the getImage function as imports at the top of the src/pages/about.js file:
import { GatsbyImage, getImage } from "gatsby-plugin-
image";
- Modify your about page's query so that it includes the prismicProfile source:
export const query = graphql'
{
markdownRemark(frontmatter: { type: { eq: "bio" }
}) {
html
}
prismicProfile {
data {
photo {
localFile {
childImageSharp {
gatsbyImageData(layout: FULL_WIDTH)
}
}
}
}
}
}
';
We utilize gatsbyImageData within our query and can make use of any of the configuration options that it supports. Here, we are specifying that the image should be full width.
- Use the new data within the data prop to get the image within the component:
const {
markdownRemark: { html },
prismicProfile: {
data: {
photo: { localFile },
},
},
} = data;
const profileImage = getImage(localFile);
First, retrieve the prismicProfile data from the data prop and then use the getImage utility from gatsby-plugin-image to retrieve the image data that's required to render it and assign it to a const called profileImage.
- Render your image within your return statement:
<GatsbyImage
image={profileImage}
alt="Your alt text"
className="mx-auto max-w-sm"
/>
Use the const parameter defined in Step 12 to render the image within a GatsbyImage component. Be sure to provide it with alt text to keep your image accessible – you could provide this via frontmatter as well if you wish.
- Restart your development server and admire your hard work by navigating to your about page.
You should now feel comfortable using images and sourcing images via the Prismic CMS. While we have only looked at two CMSes, these concepts can be taken and applied to any headless CMS that supports images. Now, let's summarize what we have learned in this chapter.
Summary
In this chapter, we learned about images on the web, and how critical they are to our browsing experience. We learned about gatsby-plugin-image and implemented the two contained image components. We also learned in which circumstances to use which component.
At this stage, you should feel comfortable developing all manner of pages for your Gatsby site. In the next chapter, we will begin to look at how we can take our development site live. We will start this journey by looking at search engine optimization.