npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@sanity/image-url

v1.1.0

Published

Tools to generate image urls from Sanity content

Downloads

925,410

Readme

@sanity/image-url

Quickly generate image urls from Sanity image records.

This helper will by default respect any crops/hotspots specified in the Sanity content provided to it. The most typical use case for this is to give it a sanity image and specify a width, height or both and get a nice, cropped and resized image according to the wishes of the content editor and the specifications of the front end developer.

In addition to the core use case, this library provides a handy builder to access the rich selection of processing options available in the Sanity image pipeline.

Getting started

npm install --save @sanity/image-url

Usage

The most common way to use this library in your project is to configure it by passing it your configured sanityClient. That way it will automatically be preconfigured to your current project and dataset:

import React from 'react'
import myConfiguredSanityClient from './sanityClient'
import imageUrlBuilder from '@sanity/image-url'

const builder = imageUrlBuilder(myConfiguredSanityClient)

function urlFor(source) {
  return builder.image(source)
}

Then you can use the handy builder syntax to generate your urls:

<img src={urlFor(author.image).width(200).url()} />

This will ensure that the author image is always 200 pixels wide, automatically applying any crop specified by the editor and cropping towards the hot-spot she drew. You can specify both width and height like this:

<img src={urlFor(movie.poster).width(500).height(300).url()}>

There are a large number of useful options you can specify, like e.g. blur:

<img src={urlFor(mysteryPerson.mugshot).width(200).height(200).blur(50).url()}>

Note that the url() function needs to be the final one in order to output the url as a string.

Builder methods

image(source)

Specify the image to be rendered. Accepts either a Sanity image record, an asset record, or just the asset id as a string. In order for hotspot/crop processing to be applied, the image record must be supplied, as well as both width and height.

dataset(dataset), projectId(projectId)

Usually you should preconfigure your builder with dataset and project id, but even when you did, these let you temporarily override them if you need to render assets from other projects or datasets.

width(pixels)

Specify the width of the rendered image in pixels.

height(pixels)

Specify the height of the rendered image in pixels.

size(width, height)

Specify width and height in one go.

focalPoint(x, y)

Specify a center point to focus on when cropping the image. Values from 0.0 to 1.0 in fractions of the image dimensions. When specified, overrides any crop or hotspot in the image record.

blur(amount), sharpen(amount), invert()

Apply image processing.

rect(left, top, width, height)

Specify the crop in pixels. Overrides any crop/hotspot in the image record.

format(name)

Specify the image format of the image. 'jpg', 'pjpg', 'png', 'webp'

auto(mode)

Specify transformations to automatically apply based on browser capabilities. Supported values:

  • format - Automatically uses WebP if supported

orientation(angle)

Rotation in degrees. Acceptable values: 0, 90, 180, 270

quality(value)

Compression quality, where applicable. 0-100

forceDownload(defaultFileName)

Make this an url to download the image. Specify the file name that will be suggested to the user.

flipHorizontal(), flipVertical()

Flips the image.

crop(mode)

Specifies how to crop the image. When specified, overrides any crop or hotspot in the image record. See the documentation for details.

fit(value)

Configures the fit mode. See the documentation for details.

dpr(value)

Specifies device pixel ratio scaling factor. From 1 to 3.

saturation(value)

Adjusts the saturation of the image. Currently the only supported value is -100 - meaning it grayscales the image.

ignoreImageParams()

Ignore any specifications from the image record (i.e. crop and hotspot).

url(), toString()

Return the url as a string.

pad(value)

Specify the number of pixels to pad the image.

vanityName(fileName)

Specify a "vanity name" for the image. This is useful for SEO purposes and is added to the end of the URL. For example:

urlFor('image-928ac96d53b0c9049836c86ff25fd3c009039a16-200x200-png').vanityName('myImage.png')
// https://cdn.sanity.io/…/928ac96d53b0c9049836c86ff25fd3c009039a16-200x200.png/myImage.png

frame(value)

Specify the frame of an animated image to transform. Acceptable values:

  • 1 - Returns the first frame of the animated image as a static preview of the image.

Deprecated: minWidth(pixels), maxWidth(pixels), minHeight(pixels), maxHeight(pixels)

Specifies min/max dimensions when cropping.

Deprecated: You usually want to use width/height with a fit mode of max or min instead.

Custom CDN domains

ℹ️ This feature is available to select Enterprise accounts. Get in touch with your sales executive to learn more.

You can specify a custom baseUrl in the builder options in order to override the default (https://cdn.sanity.io):

import imageUrlBuilder from '@sanity/image-url'

const builder = imageUrlBuilder({
  baseUrl: 'https://my.custom.domain',
  projectId: 'abc123',
  dataset: 'production',
})
const urlFor = (source) => builder.image(source)

urlFor('image-928ac96d53b0c9049836c86ff25fd3c009039a16-200x200-png')
  .auto('format')
  .fit('max')
  .width(720)
  .toString()

// output: https://my.custom.domain/images/abc123/production/928ac96d53b0c9049836c86ff25fd3c009039a16-200x200.png?auto=format&fit=max&w=720

If you already have a configured client instance:

import imageUrlBuilder from '@sanity/image-url'
import myConfiguredClient from './mySanityClient'

const builder = imageUrlBuilder({
  ...myConfiguredClient.config(),
  baseUrl: 'https://my.custom.domain',
})

License

MIT © Sanity.io