Skip to content

Working with Images Across the Website

Jump to bottom
Maanas edited this page Aug 26, 2024 · 3 revisions

This guide covers best practices for handling images throughout the project. For detailed information on Gatsby’s image handling, refer to the Gatsby Image Documentation, which provides an overview and links to related articles.

Table of Contents

How to add images to the Website

  • Please keep all the images to be used anywhere on the website inside the /src/images directory, and use them from there.
  • Please do not keep the images inside the /static directory. Keeping images there would not allow Gatsby to pre-process the images and hence would be highly inefficient.
  • There are some exceptions where using the Static folder can be useful like for storing the pdf files. Please refer to the Exceptions with the "Static" Folder section for more details.
  • After adding the image in the /src/images directory, if the image is required to be used in JS or JSX files, please refer to the Using Images inside JS & JSX files section.
  • If the image is required to be used in an MDX or MD file, please refer to the Using images in MDX or MD files section.

Exceptions with the "Static" Folder

  • Ref: Gatsby Static Folder Documentation
  • To access assets from the static folder in a Gatsby project, use a relative path starting from the root of the project. For example, if an asset is stored at static/my-file.pdf, it can be referenced in the project as /my-file.pdf.
  • Gatsby documentation generally advises against using the static folder due to several drawbacks, including the lack of post-processing for images and the absence of compile-time error checking if the source is not found.
  • Nevertheless, the static folder can be beneficial in specific scenarios. For instance, it is suitable for storing files that do not require pre-processing, such as PDFs, or for files that are too small to benefit from Gatsby’s image processing, like SVGs and icons.
  • However, it is recommended to store icons and SVGs in the images directory rather than the static folder. This practice maintains a clearer organization of assets.
  • Non-image files, such as PDFs, can be appropriately placed in the static folder.
  • For handling a large number of images used dynamically, such as in interactive visualizations, the static folder proves to be a practical choice. For further details, refer to the Gatsby Static Folder Documentation.

Using Images throughout the project

Using Images inside JS & JSX files

  • Please store all the image files needed inside the /src/images directory and use them from there.
  • To process and render images efficiently, Gatsby's gatsby-plugin-images plugin is used throughout the project.
  • Using components from this plugin helps in the efficient rendering of images with functionalities like lazy loading, preventing layout shifts, and more. Gatby recommends using it whenever it is possible.
  • It provides 2 components, one is the StaticImage component and the other is the GatsbyImage component.

The StaticImage component for static images

  • Used for rendering static images whose URLs are directly accessible.
  • If you have kept an image inside the /src/images directory and want to render it somewhere, use this component.
  • This component won't render an image if the URL is dynamic for instance if the URL is coming from a prop or there is an array of URLs and images have to be rendered from that array. Several examples of correct usage can be found here.
  • This is because every image that is to be rendered inside this component is processed at build time.
  • For example, if an image is referenced via a cloud URL and the image is updated at that URL after the project is built, the change will not be reflected on the website. Gatsby downloads and caches resources at build time, meaning the previously cached image will be used. To see the updated image, the project needs to be rebuilt.
  • Example Usage 
    import StaticImage form "gatsby-plugin-image"
 // rest of the code
<StaticImage src="../images/my-img.png" alt="image" objectFit="cover" >
  • There are other properties of the component as well. Everything is listed in the documentation. Some of the important specific sections are Shared Props, Required Props for StaticImage component, and Image Options.

The GatsbyImage component for dynamic images

  • This is used to render images dynamically.
  • It does not accept a URL, but a gatsbyImageData resolver as the image prop. This resolver only comes from the GraphQL query of image file nodes.
  • We can also make our custom resolver to process an image. (There can be some limitations like lazy loading, refer to the referenced doc for more info). Ref: https://www.gatsbyjs.com/docs/how-to/plugins-and-themes/adding-gatsby-image-support/
  • This component has to be used to render the images coming from GarphQL queries.
  • The following example has been taken from the plugin documentation. The below example with more details can be found here. In this example, the queried image from GraphQL is being displayed through GatsbyImage. : 
    import { graphql } from "gatsby"
import { GatsbyImage, getImage } from "gatsby-plugin-image"

function BlogPost({ data }) {
  const image = getImage(data.blogPost.avatar)
  return (
    <section>
      <h2>{data.blogPost.title}</h2>
      <GatsbyImage image={image} alt={data.blogPost.author} />
      <p>{data.blogPost.body}</p>
    </section>
  )
}

export const pageQuery = graphql`
  query {
    blogPost(id: { eq: $Id }) {
      title
      body
      author
      avatar {
        childImageSharp {
          gatsbyImageData(
            width: 200
            placeholder: BLURRED
            formats: [AUTO, WEBP, AVIF]
          )
        }
      }
    }
  }
`
  • NOTE: The src of the queried image can also be extracted with the help of the getSrc function from the "gatsby-plugin-image". Pass the queried file inside it to get the source of the image (like the file is being passed in the getImage function in the above example) and that source can be used in the normal img tag or similar component, just like we normally render images. However, it will not work with the StaticImage component. But note that this approach is not recommended, if the images are being queried from GraphQL, using the GatsbyImage component is the best practice.
  • There are other properties of the component as well. Everything is listed in the documentation. Some of the important specific sections are Shared Props, Required Props for GatsbyImage component, and Image Options.

All other cases

  • For all other small cases, we could use the normal img tag or the Image tag from the grommet library (or any other similar component).
  • The need for this could come when we are trying to process some images dynamically and we do not want to make a graphQL query for that (or cannot make one) or we do not want to make a custom resolver.
  • For GIFs, Gatsby recommends using the normal img tag. Ref: https://www.gatsbyjs.com/docs/how-to/images-and-media/working-with-gifs/
  • Please refer to the relative URLs section before using these tags.

Using images in MDX or MD files

For Cover Images

  • For the cover, instead of providing a path from the static folder, please use the images directory (or any directory that is being processed by the gatsby-source-filesystem plugin in the gatsby-config file) from now on, this is very crucial as the cover images won't get rendered otherwise.

  • Instead of this (using a direct URL) :

    ---
name: Three Handpicked Issues
excerpt: "We have selected 3 impactful problems and scoped them down...."
author: Denny George
project: ""
date: 2024-07-17
tags: announcement
cover: /cover-handpicked-issues.jpg
---

  • Do this (relative URL):

    ---
name: Three Handpicked Issues
excerpt: "We have selected 3 impactful problems and scoped them down...."
author: Denny George
project: ""
date: 2024-07-17
tags: announcement
cover: ../images/cover-handpicked-issues.jpg
---

For Images inside the body

  • For images in the body, for Gatsby to apply all the features of gatsby-plugin-images (refer above), we would need to use the markdown syntax to render the images.
    • Syntax- 
      ![Alt Title](../images/path/to/image.jpg)
  • To change properties related to size or border or more, we can wrap the image around a div and then style that div. For most of the size and look-related properties, it would work ex-sizes, border, border radius, etc. Refer to the Using images inside a Div section for more details.
  • All MDX files in the blog and the pages directories support Tailwind to add stylings.

Other cases in markdown

  • We can use the normal img tag too to style images, but then all the Gatsby preprocessing and gatsby-plugin-images features would not be applied to it. So try to use the above syntax as much as possible.
  • For this, the image also would required to be imported as we can't use the relative URL directly inside the img tag.
  • Please refer to the relative URLs section before using these tags.

Using images inside a Div

  • We are using div to contain and control the size of images at many places in our code.
  • It is recommended to only use the width property to control the size of the images.
  • Images are restricted to not exceed the width of their parent container throughout the project, with the help of Tailwind config.
  • If the height property is being added, then make sure that the height is greater than the image's height, otherwise, the image would overflow from the div, and the content after the div would overlap with the image.
  • It is better to only use the "width" property and let the image get rendered proportionally according to it.

Relative URLs in the normal img tag or Image grommet component won't work directly

  • The relative URLs don't work inside these tags.
  • This happens in both MDX files as well as JS files
  • It only works with direct URLs like <img src="/my-img.jpg" /> would work but <img src="../images/my-img.jpg" /> won't work.
  • To solve this we can:
    • Import the image and use it.
    import myImg from "../images/my-img.jpg"
<img src={myImg} /> // Works!
    • Use require() import inside tag directly
    <img src={require(../images/my-img.jpg).default} /> // Works!

Working with GIFs

Related Pull Request

Clone this wiki locally