svelte-sanity-image Svelte Themes

Svelte Sanity Image

A Svelte component that allows you to easily create responsive images from images stored in Sanity.io

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.

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.

đź“ś License

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

Top categories

Loading Svelte Themes