Index
Edit

Image

When you create a field with the image type the user is presented with a file dialog that allows normal uploads as well as drag & drop and paste. Arrays of images accept batches of files to be dropped on them as well.

When uploading an image the reference to the file itself is not stored in the image field. Instead an image asset is created and a reference to it created in the image field. This allows you to separate between context specific data, like hotspot, crop, and captions – and the image asset itself, which you might want to re-use in many contexts.

Image assets also contain useful metadata such as Low Quality Image Previews (LQIP), palette information and original image dimension as well as aspect ratio.

Have a look at the articles on presenting Images and image URLs for how to use images in practice.

Properties

typestring

Required. Value must be set to image.

fieldsarray

An array of optional fields to add to the image record. The fields added here follow the same pattern as fields defined on objects. This is useful for adding custom properties like caption, attribution, etc. to the image record itself (see example below). In addition to the common field attributes, each field may also have an isHighlighted option which dictates whether it should be prominent in the edit UI or hidden in a dialog modal behind an edit button (see example below).

titlestring

Human readable label for the field.

namestring

Required. The field name. This will be the key in the data record.

hiddenboolean

If set to true, this field will be hidden in the Content Studio.

readOnlyboolean

If set to true, this field will not be editable in the content studio.

descriptionstring

Short description to editors how the field is to be used.

Options

metadataarray

This option defines what metadata the server attempts to extract from the image. The extracted data is writtten into the image asset. This field must be an array of strings where accepted values are exif, location, lqip and palette. Check out the usage example in this help note.

hotspotboolean

Enables the user interface for selecting what areas of an image should always be cropped, what areas should never be cropped and the center of the area to crop around when resizing. The hotspot data is stored in the image field itself, not in the image asset, so images can have different crop and center for each place they are used.

Hotspot makes it possible to responsively adapt the images to different aspect ratios at display time. The default is value for hotspot is false.

Supported image formats

Sanity allows you to upload 268 megapixel archival originals of the image types JPG, SVG, PNG, GIF or TIFF. These formats can be transcoded into JPG, PNG and WebP. Learn how in the chapter on image URLs.

Examples of image related data structures

Example of a image type object

Schema
{
  title: 'Poster',
  name: 'poster',
  type: 'image',
  options: {
    hotspot: true // <-- Defaults to false
  },
  fields: [
    {
      name: 'caption',
      type: 'string',
      title: 'Caption',
      options: {
        isHighlighted: true // <-- make this field easily accessible
      }
    },
    {
      // Editing this field will be hidden behind an "Edit"-button
      name: 'attribution',
      type: 'string',
      title: 'Attribution',
    }
  ]
}
JSON output
{
  "_type": "image",
  "asset": {
    "_type": "reference",
    "_ref": "image-S2od0Kd5mpOa4Y0Wlku8RvXE"
  },
  "caption": "This is the caption",
  "attribution": "Public domain",
  "crop": {
    "top": 0.028131868131868132,
    "bottom": 0.15003663003663004,
    "left": 0.01875,
    "right": 0.009375000000000022
  },
  "hotspot": {
    "x": 0.812500000000001,
    "y": 0.27963369963369955,
    "height": 0.3248351648351647,
    "width": 0.28124999999999994
  }
}

Example of a image asset object with metadata (location, lqip, palette and dimensions)

{
  "_createdAt": "2018-06-27T10:46:48Z",
  "_id": "image-223c27c1f0e75fe1ef494333738e2d16a8539e6a-1365x1364-svg",
  "_rev": "MGbYJ9NCiEIKUXQcjjXmmw",
  "_type": "sanity.imageAsset",
  "assetId": "223c27c1f0e75fe1ef494333738e2d16a8539e6a",
  "extension": "svg",
  "metadata": {
    "dimensions": {
      "aspectRatio": 1.000733137829912,
      "height": 1364,
      "width": 1365
    },
    "location": {
      "_type": "geopoint",
      "lat": 59.92399340000001,
      "lng": 10.758972200000017
    },
    "lqip": "data:image/jpeg;base64,/9j/2wBDAAYEBQYFBAYGBQYHBwYIChAKCgkJChQODwwQFxQYGBcUFhYaHSUfGhsjHBYWICwgIyYnKSopGR8tMC0oMCUoKSj/2wBDAQcHBwoIChMKChMoGhYaKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCj/wAARCAAUABQDASIAAhEBAxEB/8QAGQABAAIDAAAAAAAAAAAAAAAAAAYHAwUI/8QAKBAAAQQCAQIEBwAAAAAAAAAAAgEDBAUABhEHExQhQVESIiMxYXGB/8QAFQEBAQAAAAAAAAAAAAAAAAAABAX/xAAgEQACAgEEAwEAAAAAAAAAAAABAgADEQQSITETUXGB/9oADAMBAAIRAxEAPwCqej0eqhVtneWMLx0mOn0GeOfP9Zv2upVFsDcmv3GkCIwoqjbgAqqK5BdFh7RHrpFpRRvEQQ57o88/b8ZJ9ZtQ3KcVZNo07pCqk4I+Q8e/tgrCysSRkfeRL+lFNlSIrbG9EZDfsqizCO3YSBhGrkVDXtkqcKo+mMz7DCCuupkRpeQacUUxjFOQCJDsUo5U9iSnpVtNpRXQxoLo+Gkrw404PxCv8y6N92GTQa45LqmIceQ6PzGLPC+eMYa0DeJU0bHwNz1OYZDzkh9x54lJxwlIiX1VcYxipIPM/9k=",
    "palette": {
      "darkMuted": {
        "background": "#482d2c",
        "foreground": "#fff",
        "population": 15,
        "title": "#fff"
      },
      "darkVibrant": {
        "background": "#68201e",
        "foreground": "#fff",
        "population": 22,
        "title": "#fff"
      },
      "dominant": {
        "background": "#f34b3c",
        "foreground": "#fff",
        "population": 1292,
        "title": "#fff"
      },
      "lightMuted": {
        "background": "#c5837e",
        "foreground": "#000",
        "population": 31,
        "title": "#fff"
      },
      "lightVibrant": {
        "background": "#f9948c",
        "foreground": "#000",
        "population": 3,
        "title": "#fff"
      },
      "muted": {
        "background": "#ac736c",
        "foreground": "#fff",
        "population": 24,
        "title": "#fff"
      },
      "vibrant": {
        "background": "#f34b3c",
        "foreground": "#fff",
        "population": 1292,
        "title": "#fff"
      }
    }
  },
  "mimeType": "image/svg+xml",
  "originalFilename": "logo-s-red-1365x1365.svg",
  "path": "images/3do82whm/production/223c27c1f0e75fe1ef494333738e2d16a8539e6a-1365x1364.svg",
  "sha1hash": "223c27c1f0e75fe1ef494333738e2d16a8539e6a",
  "size": 1378,
  "url": "https://cdn.sanity.io/images/3do82whm/production/223c27c1f0e75fe1ef494333738e2d16a8539e6a-1365x1364.svg",
  "_updatedAt": "2018-07-30T08:07:49.238Z"
}

Previous: SlugNext: File