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.

:warning: 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.

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.

<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.

📜 License

Copyright ©2023 Tyler McRobert. Available under the MIT License.