gatsby-plugin-sanity-image

The well-considered marriage between Sanity’s image assets and Gatsby you’ve been looking for.

• Outputs a single <img> tag, no nested DOM structure to mess with
• Supports low-quality image previews out of the box, without build-time penalties (native lazy loading)
• Generates a srcSet automatically based on the width you specify in your component code (meaning you can change it on the fly!)
• Applies Sanity hotspot data as the object-position in case you need it
• Computes cropped dimensions and drops srcSet entries that are larger than the source dimensions when appropriate (follows Sanity’s image-url parameters)
• Configure image quality, resizing behavior, file format, and more with Sanity’s Image API

At a Glance

You can find the full writeup on getting going below, but in the interest of making it easy to see if this is the thing you are looking for, here’s what using it looks like:

1import Image from "gatsby-plugin-sanity-image"
2
3const YourSweetComponent = ({ image }) => (
4  <Image
5    // pass asset, hotspot, and crop fields
6    {...image}
7    // tell Sanity how large to make the image (does not set any CSS)
8    width={500}
9    // style it how you want it
10    style={{
11      width: "100%",
12      height: "100%",
13      objectFit: "cover",
14    }}
15  />
16)
17
18export default YourSweetComponent
19
20export const query = graphql`
21  {
22    sanityDocumentOfSomeKind {
23      sweetImage {
24        ...ImageWithPreview
25      }
26    }
27  }
28`

That’s the gist, folks. Read on for the full scoop!

Getting Started

Install it

1yarn add gatsby-plugin-sanity-image

Configure it

ℹ️ Note: If this is your first time adding a Gatsby plugin, be sure to read this guide first—the below is a shorthand notation.

Simple configuration:

1{
2  resolve: "gatsby-plugin-sanity-image",
3  options: {
4    // Sanity project info (required)
5    projectId: "abcd1234",
6    dataset: "production",
7  },
8}

If you have custom image types in Sanity (e.g. mainImage that is of type image) you’ll need to add one more option before you move on. Check the full example or the Configuration Directives below.

1// Full configuration:
2{
3  resolve: "gatsby-plugin-sanity-image",
4  options: {
5    // Sanity project info (required)
6    projectId: "abcd1234",
7    dataset: "production",
8
9    // Custom image types are also supported. For example, if you have a
10    // `mainImage` type in Sanity, it winds up in Gatsby as `SanityMainImage`,
11    // and so you would add "SanityMainImage" to the customImageTypes array.
12    customImageTypes: [],
13
14    // This config directive allows you to specify the field that should be
15    // retrieved and used as alt text when no `alt` prop is passed to the image
16    // component. See docs for more detail.
17    altFieldName: "alt",
18
19    // SanityImage will warn you if you do not set an alt prop/attribute. If
20    // you don't want this behavior, you can disable this here. By default this
21    // is only enabled in development.
22    warnOnMissingAlt: process.env.NODE_ENV === "development",
23
24    // When no `alt` prop is available, SanityImage can default to setting an
25    // empty string value. This can prevent accessibility audits from detecting
26    // images that should have an alt value, but enabling it allows you to only
27    // set alt text when it is needed.
28    emptyAltFallback: false,
29
30    // Additional params to pass to @sanity/image-url for every image. The
31    // default is shown here, so you can omit the directive if you are happy
32    // with what you see here.
33    defaultImageConfig: {
34      quality: 75,
35      fit: "max",
36      auto: "format",
37    },
38
39    // ########################################################################
40    // Configuration directives below this point are rarely needed. If you    #
41    // aren't confident you need them, you probably do not need them.         #
42    // ########################################################################
43
44    // If you prefer a different fragment name, such as `MagicImage`, enter it
45    // here. This needs to be unique amongst your GraphQL types. `WithPreview`
46    // will be appended for the second fragment (e.g. MagicImageWithPreview).
47    fragmentName: "Image",
48
49    // By default, image fields are typed as SanityImage, but there are cases
50    // where you might want to use a custom schema or where custom image types
51    // are not under the SanityImage type. In this case, you
52    // can alter the type that the fragment is defined
53    // on here without redefining the fragments.
54    fragmentTypeName: "SanityImage",
55
56    // If you prefer to retreive data another way or if you want to define the
57    // fragment you use separately, you can opt-out of having fragments included
58    // entirely.
59    includeFragments: true,
60  },
61}

Don’t forget to restart gatsby develop after you update your gatsby-config.js!

Usage

1. Query for the image fields
2. Pass the retrieved fields as props to the SanityImage component
3. Use it like normal—it's just an img tag! 🤯😇

Querying for image data via GraphQL

This plugin includes two GraphQL fragments that will fetch the fields needed for display from any Sanity image asset. You do not have to use them, but they are convenient and help keep you away from confusing bugs.

In most cases, you'll want to use the ImageWithPreview fragment:

1export const query = graphql`
2  {
3    sanitySomeDocument {
4      yourImageField {
5        ...ImageWithPreview
6      }
7    }
8  }
9`

This will retrieve the asset, hotspot, and crop fields and includes a low-quality image preview that will be shown while the full image is loading.

Opting out of blurry preview images

If you have an image that you do NOT want to use the preview image for, you can opt to use the simpler Image fragment instead. This has all of the same fields with the exception of the preview. This will keep your HTML files a bit lighter, but you may wind up with more cumulative layout shift as the browser fetches the image dimensions and evaluates your styles.

Note: If you are using an SVG image, you probably do not want to fetch the preview since it’ll get thrown away—the SanityImage component aborts early on SVG images to avoid generating meaningless srcSet data that reduces cache efficiency.

Using the SanityImage component

The data you fetched from GraphQL should be an object that you can expand straight into the SanityImage component and just work. If you used the ImageWithPreview fragment, SanityImage will do the right thing automatically.

1import SanityImage from "gatsby-plugin-sanity-image"
2
3const YourComponent = ({ yourImageFieldData }) =>
4  <SanityImage {...yourImageFieldData} width={300} alt="Sweet Christmas!">

1<!--
2  Using {baseUrl} below to refer to a string with this format:
3  https://cdn.sanity.io/images/{projectId}/{dataset}/{imageId}?w=300&amp;h=600&amp;q=75&amp;fit=max&amp;auto=format
4-->
5<img
6  src="{baseUrl}"
7  srcset="
8    {baseUrl}&amp;dpr=0.5  150w,
9    {baseUrl}&amp;dpr=0.75 225w,
10    {baseUrl}&amp;dpr=1    300w,
11    {baseUrl}&amp;dpr=1.5  450w,
12    {baseUrl}&amp;dpr=2    600w
13  "
14  loading="lazy"
15  alt="Sweet Christmas!"
16  class="css-1jku2jm-SanityImage"
17/>

Note that SanityImage is not doing anything to style your image based on the width or height you provide (aside from setting a class with object-position set, should you choose to use it). In practice, it's rare that these values align consistently with a particular layout, and library control of this makes it difficult to predict the output given a particular input.

Instead you can style the resulting img tag just like any other element. SanityImage will pass through className and style props, and it makes no assumptions about your image presentation.

1position: absolute;
2width: 10px !important; /* must be > 4px to be lazy loaded */
3height: 10px !important; /* must be > 4px to be lazy loaded */
4opacity: 0;
5zindex: -10;
6pointerevents: none;
7userselect: none;

Component Props

For convenience, __typename, _type, and _key props will be ignored. Other props will be passed through to the final img element (e.g. native HTML attributes).

_{*️⃣ = Required}

Options

Configuration Directives

_{*️⃣ = Required}

The default value for defaultImageConfig is as follows:

1{
2  quality: 75,   // use reasonable lossy compression level
3  fit: "max",    // like `object-fit: contain`, but never scaling up
4  auto: "format" // automatically select next-gen image formats on supporting browsers
5}

More things to know

• If you don't specify width the uploaded image width is used.
• You are encouraged to use the sizes attribute to steer browsers to select the most appropriate image from the srcSet based on the viewport width
• You can target the low-quality image preview element via img[data-lqip] should you want to style it differently

License

Copyright ©2022 Corey Ward. Available under the MIT License.