Skip to content

Image

Schema type for uploading, selecting and editing images.

A typical image field

When you create a field with the image type the user is presented with a standard file dialog that allows normal uploads as well as drag & drop and pasting of images. 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

  • REQUIREDtypestring

    Value must be set to image.

  • namestring

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

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

  • titlestring

    Human readable label for the field.

  • hiddenboolean | function

    If set to true, this field will be hidden in the studio. You can also return a callback function to use it as a conditional field.

  • readOnlyboolean | function

    If set to true, this field will not be editable in the studio. You can also return a callback function to use it as a conditional field.

  • descriptionstring

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

  • initialValueInitialValueOrResolverFunction

    The initial value used when creating new values from this type. Can be either a literal value or a resolver function that returns either a literal value or a promise resolving to the initial value.

Options

  • metadataarray

    This option defines what metadata the server attempts to extract from the image. The extracted data is written into the image asset. This field must be an array of strings where accepted values are exif, location, lqip, blurhash and palette. Read more about image metadata in this reference document.

  • 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 crops for each place they are used.

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

  • storeOriginalFilenameboolean

    This will store the original filename in the asset document. Please be aware that the name of uploaded files could reveal potentially sensitive information (e.g. top_secret_planned_featureX.pdf). Default is true.

  • acceptstring

    This specifies which mime types the image input can accept. Just like the accept attribute on native DOM file inputs, you can specify any valid file type specifier: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#Unique_file_type_specifiers

  • sourcesarray

    Lock the asset sources available to this type to a specific subset. Import the plugins by their part name, and use the import variable name as array entries. The built in default asset source has the part name part:@sanity/form-builder/input/image/asset-source-default

    Read more about custom asset sources

Validation

Learn more about validation
  • required()function

    Ensures that this field exists.

  • custom(fn)function

    Creates a custom validation rule.

Custom asset sources

You can customize what asset sources are available via plugins. In this way you can integrate with your preferred digital asset management system (DAM). Check out the current list of asset sources.

Custom asset source for Unplash.com

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 an image type object

Input

{
  title: 'Poster',
  name: 'poster',
  type: 'image',
  options: {
    hotspot: true // <-- Defaults to false
  },
  fields: [
    {
      name: 'caption',
      type: 'string',
      title: 'Caption',
    },
    {
      name: 'attribution',
      type: 'string',
      title: 'Attribution',
    }
  ]
}

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 an 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"
}

Updated on March 14, 2023

Was this article helpful?