svelte-sanity-image

A Svelte component that allows you to easily create responsive images from images stored in Sanity.io. This is powered by the Sanity Image Builder under the hood. Package Inspired by next-sanity-image.

⚠️ This package is under active development and could introduce breaking changes.

See the demo here

Features of this package:

Creates a set of responsive image sizes.
Automatically sets width and height of image tag to prevent layout shifts.
Allows for defining a custom aspect ratio.
Allows passing all standard HTMLImageElement props to component.
Defaults with configurable performance benefits like lazy loading, auto formatting to webp, and quality.
Allows for image preloading in svelte:head with the priority prop.
Provides helpful errors for malformed or empty image sources.
Includes helpful utility functions for working with sanity image image asset sources.
Fully typed and exposes relevant types.

📦 Installation

npm install @tylermcrobert/svelte-sanity-image

🚀 Usage

Start by creating a GROQ query to fetch a Sanity document containing an image.

routes/+page.ts

import type { SanityImageObject } from '@tylermcrobert/svelte-sanity-image'; // Optional typing

export async function load() {
  const imageQuery = `*[_type == 'yourDoc'][0].yourImage`;
  const image: SanityImageObject = await client.fetch(imageQuery);

  return { image };
}

Next, supply the SanityImage component with the image from Sanity along with your configured sanity client.

routes/+page.ts

<SanityImage
  {client}
  {image}
  sizes="(max-width: 600px) 480px, 800px"
  alt="The Beatles crossing Abbey Road in London."
/>

This represents a basic implementation of the component. Usage is similar to a standard <img /> tag, but instead takes a image and a client. For more details on those and other configuration options, refer to the props table.

⚙️ Component Props

Property	Type	Description	Required
`client`	Object	A configured Sanity client.	Yes
`image`	Object	Image data returned from sanity API.	Yes
`alt`	String \| null	Descriptive alt text for image accessibility.	Yes
`sizes`	String	A responsive image size string. Read more about that in the MDN image reference.	Yes
`quality`	Number	Quality 0-100. Specify the compression quality (where applicable). Defaults are 75 for JPG and WebP per Sanity's defaults.	–
`loading`	String \| null	Set the browser’s native lazy loading attribute. Available options are `"lazy"`, `"eager"`, or `null`. Defaults to `"lazy"`.	–
`autoFormat`	Boolean	Uses webp format if browser supports it. Defaults to `true`	–
`aspect`	Number	Enforces an aspect ratio on the image.	–
`onLoad`	Function	Runs on image load and provides an event object

🧰 Utilities

getReferenceId - Supplies the reference ID from any valid GROQ image asset result
getDimsFromRefString - Pulls out the original image dimensions from a reference ID.
getImageDimensions - Takes a GROQ image source and extracts the dimensions (including if the image is cropped within sanity.)

🤝 Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

tylermcrobert/svelte-sanity-image