A JavaScript library to generate image urls from Sanity image records

Image-url builder (JS)

A short introduction to Sanity.io

What you need to know

Introduction

Starter projects

Getting started with Sanity CLI

Start with CLI

Getting started

Project Structure

sanity.json

Environment variables

Sanity Studio Configuration

Configuration

Best practices for content modelling

Best practices

Naming things

Understanding content types

Content types

Content modeling in Sanity Studio

Content modelling

Early Access: Sanity UI

Styling the Studio

Styling

Previews / List Views

Preview / List View

Icons

Icons for data types

Sort Orders

Sort orders

Parts

The parts system

Plugins

Custom input components

Custom Input Components

Custom asset sources

Studio Customization

Customization

Rich Text Editor

The rich text editor

Configuring the Portable Text editor

Customizing the Portable Text editor

Previewing Portable Text

Previewing

Presenting Portable Text

Block content

Validation

Introduction to Custom Diff Components

Custom Diff Components

History experience

Document history

Dashboard

Installing and configuring widgets

Installing widgets

Creating your own widget

Create widgets

Introduction to Structure Builder

Set up Structure Builder to override the default list view

Create a link to a single edit page in your main document type list

Manually group items in a pane

Dynamically group list items with a GROQ filter

Create custom document views with Structure Builder

Structure Builder

Initial Value Templates

Document actions

Custom document badges

Document badges

Custom workflows

Introduction to the Presence API

Presence API

Hosting and deployment

Studio hosting

Preview content on site

Preview in frontend

Localization

Drafts

Experimental Features

Spaces

Action UI affordances

Studio search config

Sanity Studio

How Queries Work – GROQ

How Queries Work

Query Cheat Sheet - GROQ

Query Cheat Sheet

The Vision Plugin

GROQ Playground

Query Language (GROQ)

Query language (GROQ)

GraphQL

Assets

Asset CDN

Presenting Images

Asset pipeline

Images & assets

API CDN

Webhooks

Real-time Updates

Real-time

How to use Hot Swapping for datasets

Hot Swap

How to use Cloud Clone for datasets

Cloud Clone

Datasets

Transactions

Migrating Data

Updating Content

Updating content

IDs and Paths

IDs and paths

Importing Data

Importing data

Browser security & CORS

Access Your Data (CORS)

Access Control

Third-Party Login (SSO)

Keeping your data safe

Security

Technical limits

Data store

How to pitch Sanity.io to your team

Convince your team

Convincing your clients to go with Sanity.io, rather than a traditional CMS

Convince your clients

Pro Bono Plans

Open Source Plan

Open-source projects

Non-profit Plan

Non-profit organizations

Build with Sanity

URL Format

URL format

Authentication

Patches

Using JSONMatch

Endpoints

Export

History

Listening

Listen

Mutations

Mutate

Projects API

Projects

Jobs API

Jobs

Queries

Query

HTTP API

Syntax

Data Types

Operators

Functions

Pipeline Components

Joins

Query Language (GROQ) 

Array

Block

Boolean

Date

Datetime

Document

File

Geopoint

 Image

Number

Object

Reference

Slug

String

Span

Text

Schema Types

Schema types

Build

CORS

Dataset

Debug

Deploy

Docs

Documents

Exec

Help

Hook

Init

Install

Login

Logout

Manage

Start

Versions

Undeploy

Upgrade

Command line interface

JavaScript

.NET

Client libraries

Structure Builder Reference

Structure builder

Initial Value Templates API

Reference docs

# @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](https://www.npmjs.com/package/@sanity/client). That way it will automatically be preconfigured to your current project and dataset:

```js
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:

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

This will ensure that the author image is alway 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:

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

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

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

### `minWidth(pixels)`, `maxWidth(pixels)`, `minHeight(pixels)`, `maxHeight(pixels)`

Specifies min/max dimensions when cropping

### `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](https://www.sanity.io/docs/reference/image-urls#crop-object-object) for details.

### `fit(value)`

Configures the fit mode. See the [documentation](https://www.sanity.io/docs/reference/image-urls#fit-object-object) 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.
