Image

Schema type for uploading, selecting, and editing images.

When you create a field with the image type, editors see a standard file dialog for uploads, drag and drop, and pasting images. Arrays of images accept batches of files to be dropped on them. See the ImageDefinition reference for the full type definition.

When you upload an image, the image field doesn't store a reference to the file itself. Instead, it stores a reference to the asset metadata document. This lets you separate context-specific data, like hotspot, crop, and captions, from the image asset itself, which you might want to reuse in many contexts.

Image assets also contain metadata such as low-quality image previews (LQIP), BlurHash and ThumbHash placeholders, palette information, and the original image dimensions and aspect ratio.

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

Properties

  • Requiredtype

    string

    Value must be set to image.

  • Requiredname

    string

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

  • fields

    array

    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 to the image record itself, such as caption and attribution. For an example, see "Example of an image type object."

  • title

    string

    A human-readable label for the field. This is what's displayed in Studio. If omitted, the name will be used.

  • hidden

    boolean

    If set to true, this field is hidden in the studio. You can also provide a callback function to make it a conditional field. (Defaults to false)

  • readOnly

    boolean

    If set to true, this field isn't editable in the studio. You can also provide a callback function to make it a conditional field. (Defaults to false)

  • description

    string

    A short description to help editors understand how the field is to be used.

  • initialValue

    any | resolver function

    The initial value used when creating new values of this type. Can be a literal value, or a resolver function that returns a literal value or a promise that resolves to one. Learn more about initial value templates.

  • deprecated

    object

    Marks a field or document type as deprecated in the studio interface and displays a user-defined message. Accepts an object with a single reason key that accepts a string with the reason.

    For example: deprecated: { reason: 'no longer used' }

    If you deploy a GraphQL API schema, this property is translated into the @deprecated directive.

  • options

    object

    Accepts further configuration options. For the available options, see the Options section on this page.

  • validation

    function

    Lets you specify validation rules. For the available validation functions, see the Validation section on this page.

  • icon

    Supply a custom icon for this field. For more information, see Icons.

  • components

    Lets you provide custom components to override the studio defaults in various contexts. The available keys are annotation, block, diff, field, inlineBlock, input, item, and preview. This property is in beta.

  • fieldsets

    Groups fields together in the studio interface. Each fieldset has a name, title, and optional options for collapsing behavior.

  • preview

    Configures how the document or object is previewed in lists and references. Accepts select and prepare properties.

  • renderMembers

    Callback that receives the members of the image input (its fields and fieldsets) and returns a modified array of members, for example to add decoration members. This property is in beta.

Options (ImageOptions)

  • metadata

    array

    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 image, exif, location, lqip, blurhash, thumbhash, and palette. By default, Sanity extracts blurhash, thumbhash, lqip, and palette, but not image, exif, or location. Read more about image metadata.

  • hotspot

    object | boolean

    Enables the user interface in Studio 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. Accepts an object with a previews array, which accepts an array of objects containing title and aspectRatio keys. For an example, see the Hotspot previews section on this page.

    The hotspot data is stored on the image field. See the presenting images guide for details on reading hotspot data.

    Also accepts a boolean to enable/disable the hotspot option. (Defaults to false)

  • storeOriginalFilename

    boolean

    This stores the original filename in the asset document. Be aware that the names of uploaded files can reveal sensitive information (for example, top_secret_planned_featureX.pdf). Default is true.

  • accept

    This specifies which MIME types the image input can accept. Like the accept attribute on native DOM file inputs, you can specify any valid file type specifier: View available types.

  • sources

    Lock the asset sources available to this type to a specific subset. Accepts an array of asset sources: import each asset source from its plugin, and use the imported value as an array entry.

    Read more about custom asset sources.

  • mediaLibrary

    object

    Contains a single filters array that lets you define filtered results from Media Library using GROQ query syntax. See the example in Configure Studio for Media Library.

    For use with Media Library only.

  • disableNew

    boolean

    Disables uploading of new assets to the field, limiting selection to existing assets.

  • collapsible

    If set to true, the field can be collapsed.

  • collapsed

    If set to true, the field is collapsed by default.

  • columns

    Number of columns to use for the field layout.

  • modal

    Controls how the modal (dialog for content editing) is rendered.

Validation (ImageRule)

Learn more about validation.

  • required()

    function

    Ensures that this field exists.

  • skip()

    Discards the validation rules set before it in the chain and makes the field optional. Rules chained after it still apply.

  • assetRequired()

    function

    Like required but more specific. Requires that an actual asset is referenced to validate. Must be used together with required, for example:
    validation: (Rule) => Rule.required().assetRequired()

  • custom(fn)

    function

    Creates a custom validation rule.

  • error(message)

    Sets a custom error message for the preceding validation rule.

  • warning(message)

    Sets a custom warning message for the preceding validation rule. Warnings do not prevent publishing.

  • info(message)

    Sets a custom info message for the preceding validation rule. Info messages are purely informational and do not prevent publishing.

  • valueOfField(path)

    Gets the value of a sibling field to use in validation. Useful for creating validation rules that depend on the value of another field.

Custom asset sources

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

Supported image formats

You can upload images of up to 256 megapixels in a range of formats, including JPG, PNG, GIF, TIFF, WebP, AVIF, and SVG. For the full list of supported upload formats, see Technical limits. Image transformations support JPEG, PNG, WebP, PJPG, TIFF, AVIF, and GIF source images, which can be transcoded into JPG, PNG, GIF, AVIF, and WebP. To transform an image in another format, such as SVG, convert it to a supported format first. Learn how in the chapter on image URLs.

Examples of image-related data structures

The image field type is similar to an object field, in that it can have additional fields appended to it using the fields configuration.

When an asset is uploaded to an image field, an asset metadata document is created, and a reference to that document is added to the asset field within the image field.

Example of an image type object

Input

import {defineField} from 'sanity'

defineField({
  name: 'poster',
  type: 'image',
  // 👇 Enables crop and hotspot tools
  options: {
    hotspot: true
  },
  // 👇 Optionally append additional fields to the image object
  fields: [
    defineField({
      name: 'caption',
      type: 'string',
    }),
    defineField({
      name: 'attribution',
      type: 'string',
    })
  ]
})

Response

{
  "_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 metadata document

The asset metadata document created when an asset is uploaded includes details such as location, lqip (low-quality image preview), blurHash, thumbHash, 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"
}

Uploading images with drag and drop or paste

When you drag and drop images into the Portable Text Editor or an Array field in Sanity Studio, it will automatically pick the most suitable field to add the image to based on the accept option configured on the image fields. If multiple fields match the dropped image type, it will use the first matching field.

import {defineField} from 'sanity'

// Field with accept option set to PNG
defineField({
  name: 'pngImage', 
  type: 'image',
  options: {
    accept: 'image/png'
  }
})
import {defineField} from 'sanity'

// Field with accept option set to JPEG
defineField({
  name: 'jpegImage',
  type: 'image', 
  options: {
    accept: 'image/jpeg'
  }
})

When dropping a JPEG image, it will be added to the jpegImage field that accepts JPEG images.

Hotspot previews

Use the hotspot.previews option to define the cropped previews shown in the Studio's hotspot tool.

import {defineField} from 'sanity'

defineField({
  type: 'image',
  name: 'poster',
  options: {
    hotspot: {
      previews: [
        {title: '2:1', aspectRatio: 2 / 1},
        {title: '4:5', aspectRatio: 4 / 5},
        {title: '9:16', aspectRatio: 9 / 16},
      ]
    }
  }
})

Was this page helpful?

Previous

Global document reference

Next

Number

sanity.ioAll Systems Operational© Sanity 2026
Change site theme