Form Components
The Form Components API will let you override default form widgets with your own custom components.
The following components are available for customization:
// ./sanity.config.js
export default defineConfig({
// rest of config ...
form: {
components: {
field: MyCustomField,
input: MyCustomInput,
item: MyCustomItem,
preview: MyCustomPreview,
},
},
})For a description of how these different components map to the different parts of a form field, visit the Form Components article.
Custom form components can be declared either at the configuration level, i.e. either in defineConfig or definePlugin, or in a schema. Components added at configuration level will affect all forms in the studio while components added to a schema will only affect the field or fields specified in that schema.
// ./schemas/myDocument.jsx
import {defineType} from 'sanity'
function MyStringInput(props) {
return (
<div style={{border: '4px solid magenta'}}>
{props.renderDefault(props)}
</div>
)
}
const myDocument = defineType({
name: 'myDocument',
type: 'myDocument',
title: 'My document',
fields: [
{
name: 'myTitle',
type: 'string',
title: 'My title',
components: {input: MyStringInput},
},
],
})Shared Properties
changedboolean
Whether the field value differs from the published version.
levelnumber
The nesting depth of this field in the document structure.
pathPath
The document path to this field.
presenceFormNodePresence[]
Presence indicators showing which users are viewing or editing this field.
renderDefaultfunction
Renders the default component. Call with the component props to defer to the built-in rendering.
schemaTypeSchemaType
The schema definition for this field.
validationFormNodeValidation[]
Validation markers for this field.
valueunknown
The current value of the field. The type depends on the field's schema type.
All form components receive the renderDefault method which will defer to the default studio rendering of the component when called with the component's props.
renderDefaultfunction
A callback function that renders the default layout component. The function takes the component's properties as an argument, and these properties can be modified.
In addition, each form component receives a set of props that varies in shape depending on the type of field they are assigned to.
Input components
Input components receive props that vary by field type. InputProps is a union of type-specific interfaces such as StringInputProps, ObjectInputProps, and ArrayOfObjectsInputProps. In addition to the shared properties (above), all input components have the following:
Properties
elementPropsobject
HTML element attributes to spread onto the input element, including event handlers for focus management.
focusedboolean
Whether the input currently has focus.
idstring
A unique identifier for the input element. Use this as the HTML id attribute.
onChangefunction
Callback to update the field value. Accepts a
PatchEvent, aFormPatch, or an array of patches.pathPath
The document path to this field.
readOnlyboolean
Whether the field is read-only.
validationErrorFormNodeValidation[]
Validation markers for this field.
Array item components
In addition to the shared properties (above), array item components (ItemProps) have the following:
Properties
idstring
elementPropsobject
focusedboolean
focusPathPath
membersArrayOfObjectsFormNode[]
The form nodes for each item in the array.
onChangefunction
Callback to update the array value.
onItemExpandfunction
onItemCollapsefunction
onItemClosefunction
onItemOpenfunction
onInsertfunction
Callback to insert a new item at a specific position in the array.
onItemMovefunction
Callback to reorder an item within the array.
onItemRemovefunction
onItemAppendfunction
Callback to add a new item at the end of the array.
onItemPrependfunction
Callback to add a new item at the beginning of the array.
onPathFocusfunction
onUploadfunction
resolveInitialValuefunction
Resolves the initial value for new array items.
resolveUploaderfunction
renderInputfunction
renderFieldfunction
renderItemfunction
renderPreviewfunction
Field components
In addition to the shared properties (above), field components (FieldProps) have the following:
Properties
childrenReactNode
The rendered input component for this field.
descriptionReactNode
The field description from the schema, if defined.
indexnumber
The position of this field among its siblings.
inputIdstring
The HTML id of the associated input element. Use for label association.
inputPropsInputProps
The full set of input props for the field's input component.
namestring
The field name as defined in the schema.
presenceFormNodePresence[]
titlestring
The field title from the schema, if defined.
validationFormNodeValidation[]
List preview components
In addition to the shared properties (above), list preview components (PreviewProps) have the following:
Properties
actionsReactNode
Action buttons rendered alongside the preview.
errorError | null
isPlaceholderboolean
Whether the preview is showing placeholder content while loading.
layoutstring
The preview layout variant. Common values include "default", "media", and "detail".
mediaReactNode
The media element (image, icon, or custom component) for the preview.
titleReactNode
_typestring