Studio

String

A schema type for strings and a selectable lists of strings.

Loading...
A string field with a title and a description

Short string. Typically used for titles, names, and labels. If you need a basic multi-line string input, use the text. If you need text with markup and structured data, use block. See the StringDefinition reference for the full type definition.

Properties

  • Requiredtype

    Required. Value must be set to string.

  • Requiredname

    Required. The field name. This is the key in the data record.

  • title

    Human-readable label for the field.

  • hidden

    If set to true, the field is hidden in the studio. You can also set it to a callback function to make it a conditional field.

  • readOnly

    If set to true, the field can't be edited in the studio. You can also set it to a callback function to make it a conditional field.

  • description

    Short description that tells editors how to use the field.

  • initialValue

    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.

  • deprecated

    Marks a field or document type as deprecated in the studio interface and displays a user-defined message defined by the single required reason property.

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

  • 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 diff, field, input, item, and preview.

  • placeholder

    Placeholder text shown in the input when it has no value.

Options (StringOptions)

  • list

    A list of predefined values that the user can choose from. The array can either include string values ['sci-fi', 'western'] or objects [{title: 'Sci-Fi', value: 'sci-fi'}, ...].

    Sanity Studio displays string values with the first character capitalized and the rest lowercased: sci-fi displays as Sci-fi, and USA displays as Usa. The stored value doesn't change. To control the displayed label, use object values with a title instead.

  • layout

    Controls how the items defined in the list option are presented. If set to 'radio' the list will render radio buttons. If set to 'dropdown' you'll get a dropdown menu instead. Default is dropdown.

  • direction

    Controls how radio buttons are lined up. Use direction: 'horizontal|vertical' to render radio buttons in a row or a column. Default is vertical. Will only take effect if the layout option is set to radio.

  • search

    Sets a search weight for this field so that it ranks higher when editors search in the studio. Takes {weight: number}. The default weight is 1, or 10 if the field is selected as the preview title and 5 if it is selected as the subtitle. A weight set here overrides both. See Studio search configuration.

Dropdown empty option

When layout: 'dropdown' (the default layout) is used on a field with options.list, the input renders a blank option at the top of the list representing the unset state. Selecting it clears the field's value. This blank option is built into the dropdown input and cannot be removed, renamed, or restyled through schema configuration.

What schema configuration can and cannot change:

  • Cannot remove the blank option: required() validation, initialValue, and none of the available options fields remove it from the rendered list.
  • Cannot rename the blank option: its title is hardcoded to an empty string.
  • Can switch to layout: 'radio': radio layout does not include a blank option. Editors can still unset the field with the Clear button, which appears once a value is selected.
  • Can implement a custom input component: for full control over placeholder text, empty-option behavior, and item rendering.

Workarounds

Use radio layout: switch from layout: 'dropdown' to layout: 'radio' to avoid the blank option entirely:

import {defineField} from 'sanity'

defineField({
  name: 'status',
  type: 'string',
  options: {
    list: ['draft', 'published', 'archived'],
    layout: 'radio',
  },
})

Custom input component for full control: for full control over rendering, including placeholder text and conditional logic, implement a custom input. See Create a visual string selector field input.

Dynamic option lists

The options.list property only accepts a static array of strings or {title, value} objects. It does not accept a function or callback. When you use defineField, TypeScript reports this at compile time. If you need a dynamic list (filtered by another field, fetched at runtime, conditionally shown), implement a custom input component.

Register a custom input on the field, then build the option list inside your component. Use useFormValue to read other fields on the current document, or fetch data through @sanity/client. For an example of the custom input pattern, see Create a visual string selector field input.

import {defineField} from 'sanity'
import {DynamicStatusInput} from './DynamicStatusInput'

defineField({
  name: 'status',
  type: 'string',
  components: {
    input: DynamicStatusInput,
  },
})

Dynamic options.list support is tracked in GitHub issue #4095.

Validation (StringRule)

  • required()

    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. Requires sanity 5.9.0 or later.

  • min(minLength)

    Minimum length of string.

  • max(maxLength)

    Maximum length of string.

  • length(exactLength)

    Exact length of string.

  • uppercase()

    All characters must be uppercase.

  • lowercase()

    All characters must be lowercase.

  • email()

    Value must be a valid email address.

  • regex(pattern[, options])

    String must match the given pattern.

    options is an optional object. You can set options.name and options.invert.

    Providing a name makes the message more understandable to the user (Does not match "<name>"-pattern).

    Set invert to true to allow any value that does not match the pattern.

    With invert: true, the message reads Should not match "<name>"-pattern.

    You can also pass the name as a string: regex(pattern, name). The three-argument form regex(pattern, name, options) is accepted, but its options argument is ignored. To use invert, pass {name, invert} as the second argument.

  • custom(fn)

    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.

Examples

Field configuration

import {defineField} from 'sanity'

defineField({
  title: 'Title',
  name: 'title',
  type: 'string',
  description: 'Make it catchy',
  validation: (Rule) => Rule.max(120).warning(`A title shouldn't be more than 120 characters.`),
})

List of predefined strings

Protip

Want to make a multi-select for strings? Check out the Array schema type to see how you can build an array of strings, references, objects, and more.

For details on how to access the title value of a list in your document list preview, see Previewing from predefined string lists.

Set an initial value for string fields

You can use initial values to preset string fields on document creation:

import {defineField, defineType} from 'sanity'

export default defineType({
  name: 'post',
  type: 'document',
  title: 'Post',
  initialValue: {
    title: 'The initial title',
  },
  fields: [
    defineField({
      name: 'title',
      type: 'string',
      title: 'Title',
    }),
  ],
})
Previous

Span

Next

Text

Was this page helpful?