Image
Schema type for uploading, selecting, and editing images.
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 and drop and pasting of images. Arrays of images accept batches of files to be dropped on them.
When uploading an image the reference to the file itself is not stored in the image field in a given document. Instead, it adds a reference to the asset metadata document. 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 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.REQUIREDnamestring
The field name. This will be the key in the data record.
fieldsarray
An array of optional fields to add to the
imagerecord. The fields added here follow the same pattern as fields defined on objects. This is useful for adding custom properties likecaption,attribution, etc., to the image record itself (see example below).titlestring
Human readable label for the field.
boolean | 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.
deprecated{ reason: String }
Marks a field or document type as deprecated in the studio interface and displays a user-defined message defined by the single required
reasonproperty.If you deploy a GraphQL API schema, this property will translated into the
@deprecateddirective.
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 areimage,exif,location,lqip,blurhashandpalette. 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
imagefield itself, not in theimage 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
hotspotisfalse.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 istrue.acceptstring
This specifies which mime types the image input can accept. Just like the
acceptattribute 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_specifierssourcesarray
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
Validation
Learn more about validationrequired()function
Ensures that this field exists.
assetRequired()function
Like
requiredbut more specific. Requires that an actual asset is referenced to validate. Must be used together withrequired, i.e.:validation: (Rule) => Rule.required().assetRequired(),custom(fn)function
Creates a custom validation rule.
You can customize what asset sources are available via plugins. This way, you can integrate with your preferred digital asset management system (DAM). Check out the current list of asset sources.
Sanity allows you to upload 256-megapixel archival originals of the image types JPG, SVG, PNG, GIF, or TIFF. These formats can be transcoded into JPG, PNG, GIF, AVIF, and WebP. Learn how in the chapter on image URLs.
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
}
}{
"_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"
}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.
// Field with accept option set to PNG
defineField({
name: 'pngImage',
type: 'image',
options: {
accept: 'image/png'
}
})// 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.