Aspect patterns
Common patterns for defining aspects
The Create an aspect guide covers how to define and deploy an aspect. This guide explores common patterns for defining aspects.
Prerequisites: sanity CLI v3.88.0 or newer.
Code-based features not supported
Aspects cannot include executable code such as custom validation functions, custom components, or callbacks (for example, hidden or readOnly). Aspects also don't support the image, file, reference, crossDatasetReference, or document types. Use static configuration only.
Aspect with a single string field
import {defineAssetAspect} from 'sanity'
export default defineAssetAspect({
name: 'copyright',
title: 'Copyright',
type: 'string',
description: 'Enter the copyright value for this asset.',
})Aspect with a single boolean field
import {defineAssetAspect} from 'sanity'
export default defineAssetAspect({
name: 'placeholder',
title: 'Placeholder',
type: 'boolean',
initialValue: false,
description: 'Set to true for temporary placeholder assets.',
})Aspect with multiple fields
import {defineAssetAspect, defineField} from 'sanity'
export default defineAssetAspect({
name: 'copyright',
title: 'Copyright',
type: 'object',
fields: [
defineField({
name: 'copyrightHolder',
title: 'Copyright Holder',
type: 'string',
}),
defineField({
name: 'copyrightDate',
title: 'Date',
type: 'date',
}),
],
})Aspect with a global document reference
You can combine aspects with global document references. Use the globalDocumentReference type to target documents in another project and dataset. This example targets a photographer type in the example dataset of the project identified by <your-project-id>.
import { defineAssetAspect } from 'sanity'
export default defineAssetAspect({
name: 'photographer',
title: 'Photographer',
type: 'globalDocumentReference',
description: 'Select the photographer.',
resourceType: 'dataset',
resourceId: 'YOUR_PROJECT_ID.example',
weak: true,
to: [
{
type: 'photographer',
preview: {
select: {
title: 'name'
}
}
}
]
})The resourceId value is the <your-project-id>.DATASET_NAME. As with normal references in Sanity Studio, you can use the preview property to select fields to display. In this case, it sets the preview title to the photographer.name field.
Learn more about global document references.
Public aspects
To query an aspect value from a dataset, mark the aspect definition as public.
import {defineAssetAspect, defineField} from 'sanity'
export default defineAssetAspect({
name: 'copyright',
title: 'Copyright',
type: 'object',
fields: [
defineField({
name: 'copyrightHolder',
title: 'Copyright Holder',
type: 'string',
}),
defineField({
name: 'copyrightDate',
title: 'Date',
type: 'date',
}),
],
public: true
})Marking an aspect as public lets a dataset resolve the aspect value with media::aspect(MEDIA_REF, "NAME"), where MEDIA_REF is a reference to the media asset and NAME is the aspect name.