Hide a deprecated field in new documents

Simplify your Studio experience by hiding deprecated fields when you create new documents.

/schemas/documents/article.ts

import { defineField, defineType } from 'sanity';

export default defineType({
  name: 'article',
  title: 'Article',
  type: 'document',
  fields: [
    defineField({
      name: 'title',
      title: 'Title',
      type: 'string',
      readOnly: true,
      deprecated: {
        reason: 'Use the "name" field instead',
      },
      hidden: ({ value }) => (value === undefined ? true : false),
    }),
    defineField({
      name: 'name',
      title: 'Name',
      type: 'string',
    }),
  ],
});

The release of Studio v3.26.0 enables us to deprecate fields, which sets them apart in the Studio with a caution label and reason for deprecation. This helps guide your users as you migrate the content in those fields, but that deprecated field will continue to show up in new documents. You might mitigate this by setting the field to read-only (so users can't continue to add content to it), but this may still cause unnecessary confusion.

By using the hidden property alongside the deprecated property, we can have the Studio intelligently return the deprecated field—and its content—only when there is something to show. Since new documents start with empty fields, the deprecated field will be hidden in new documents as they are created, while existing documents that had content in that field will continue to show the field.

Note that this approach will also hide the field in existing documents where the value was undefined (i.e., empty). This is probably what you want anyway, but if not, this approach may not be for you.

Contributor

Geoff Ball

Support Engineer at Sanity.io

Canada