Corey Ward
Consultant, Senior Web Developer @ Figma
Easily leverage the power of Sanity's image API from React-based environments like Gatsby.
The well-considered marriage between Sanity’s image assets and Gatsby you’ve been looking for.
<img>
tag, no nested DOM structure to mess withsrcSet
automatically based on the width
you specify in your
component code (meaning you can change it on the fly!)object-position
in case you need itsrcSet
entries that are larger than
the source dimensions when appropriate (follows Sanity’s image-url parameters)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:
import Image from "gatsby-plugin-sanity-image"
const YourSweetComponent = ({ image }) => (
<Image
// pass asset, hotspot, and crop fields
{...image}
// tell Sanity how large to make the image (does not set any CSS)
width={500}
height={300}
// style it how you want it
style={{
width: "100%",
height: "100%",
objectFit: "cover",
}}
/>
)
export default YourSweetComponent
export const query = graphql`
{
sanityDocumentOfSomeKind {
sweetImage {
...ImageWithPreview
}
}
}
`
That’s the gist, folks. Read on for the full scoop!
yarn add gatsby-plugin-sanity-image
ℹ️ 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:
{
resolve: "gatsby-plugin-sanity-image",
options: {
// Sanity project info (required)
projectId: "abcd1234",
dataset: "production",
},
}
// Full configuration:
{
resolve: "gatsby-plugin-sanity-image",
options: {
// Sanity project info (required)
projectId: "abcd1234",
dataset: "production",
// Additional params to include with every image.
// This is optional and the default is shown
// below—if you like what you see, don’t set it.
defaultImageConfig: {
quality: 75,
fit: "max",
auto: "format",
},
// If you prefer a different fragment name, such
// as `MagicImage`, enter it here. This needs to
// be unique your GraphQL types. `WithPreview`
// will be appended for the second fragment (e.g.
// MagicImageWithPreview).
fragmentName: "Image",
// By default, image fields are typed as SanityImage,
// but there are cases where you might want to use
// a custom schema or where custom image types are
// not under the SanityImage type. In this case, you
// can alter the type that the fragment is defined
// on here without redefining the fragments.
fragmentTypeName: "SanityImage",
// If you prefer to retreive data another way or
// if you want to define the fragment you use
// separately, you can opt-out of having fragments
// included entirely.
includeFragments: true,
// This config directive allows you to specify the
// field that should be retrieved and used as alt
// text when no `alt` prop is passed to the image
// component. See docs for more detail.
altFieldName: "alt",
// Custom image types are also supported; refer to
// full documentation for usage instructions.
customImageTypes: [],
},
}
Don’t forget to restart gatsby develop
after you update your
gatsby-config.js
!
SanityImage
componentimg
tag! 🤯😇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:
export const query = graphql` { sanitySomeDocument { yourImageField { ...ImageWithPreview } } } `
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.
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.
SanityImage
componentThe 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.
import SanityImage from "gatsby-plugin-sanity-image"
const YourComponent = ({ yourImageFieldData }) =>
<SanityImage {...yourImageFieldData} width={300} alt="Sweet Christmas!">
<!--
Using {baseUrl} below to refer to a string with this format:
https://cdn.sanity.io/images/{projectId}/{dataset}/{imageId}?w=300&h=600&q=75&fit=max&auto=format
-->
<img
src="{baseUrl}"
srcset="
{baseUrl}&dpr=0.5 150w,
{baseUrl}&dpr=0.75 225w,
{baseUrl}&dpr=1 300w,
{baseUrl}&dpr=1.5 450w,
{baseUrl}&dpr=2 600w
"
loading="lazy"
alt="Sweet Christmas!"
class="css-1jku2jm-SanityImage"
/>
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.
SanityImage
is relying on browser-native deferred image loading. This
generally works fine in browsers that support it, but there are situations where
the unloaded image is hidden or covered, resulting in the full image never
loading.
If this happens, you can override the styles set on the full-size image using
the img[data-loading]
selector. This image sits immediately adjacent to the
spaceball image and has the following default styles while loading:
position: absolute;
width: 10px !important; /* must be > 4px to be lazy loaded */
height: 10px !important; /* must be > 4px to be lazy loaded */
opacity: 0;
zindex: -10;
pointerevents: none;
userselect: none;
*️⃣ = Required
| Option | Type | Default | Description |
| -------------------- | ------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| projectId
*️⃣ | String | | Sanity Project ID |
| dataset
*️⃣ | String | | Sanity Dataset ID |
| fragmentName
| String | "Image"
| If you prefer a different fragment name, such as MagicImage
, enter it here. This needs to be unique your GraphQL types. WithPreview
will be appended for the second fragment (e.g. MagicImageWithPreview). |
| fragmentTypeName
| String | "SanityImage"
| By default, image fields are typed as SanityImage, but there are cases where you might want to use a custom schema or where custom image types are not under the SanityImage
type. In this case, you can alter the type that the fragment is defined on without redefining the fragments. |
| includeFragments
| Boolean | true
| If you prefer to retreive data another way or if you want to define the fragment you use separately, you can opt-out of having fragments included entirely. |
| customImageTypes
| Array | []
| If you would like to use the Image
and ImageWithPreview
fragments on custom image types, specify all custom type names in the customImageTypes
array. For more detail, follow this guide. |
| altFieldName
| String | null
| If you are adding alt text directly to image assets in your Sanity Studio (e.g. via a plugin like sanity-plugin-media), this plugin can include that field in the Image
and ImageWithPreview
fragments and utilize it as the default/fallback alt
attribute value when no alt
prop is passed to the SanityImage
component. |
| defaultImageConfig
| Object | See below. | Additional params to pass to the Sanity image URL builder. These will be converted into function calls against @sanity/image-url
. Here is the full list of methods available. |
The default value for defaultImageConfig
is as follows:
{
quality: 75, // use reasonable lossy compression level
fit: "max", // like `object-fit: contain`, but never scaling up
auto: "format" // automatically select next-gen image formats on supporting browsers
}
width
the uploaded image width is used.sizes
attribute to steer browsers to select
the most appropriate image from the srcSet
based on the viewport widthimg[data-lqip]
should you want to style it differentlyThis project is licensed under the Mozilla Public License 2.0, which is a copyleft license with a share-alike provision. Please contribute meaningful improvements back to the open-source community, either via direct contribution or by releasing a separate library!
yarn add gatsby-plugin-sanity-image
Consultant, Senior Web Developer @ Figma
A collection of utilities formulated to provide positive experiences in the Sanity Studio.
Go to Sanity PillsAn easy way to render Portable Text block content in React applications.
Go to React Portable Text