sanity-plugin-conditional-field
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.0 • Public • Published

    sanity-plugin-conditional-field

    Hide or show a Sanity.io field based on a custom condition set by you.


    🚨 Warning: the Sanity team has voiced they're currently working on a native solution. The goal of this plugin is to become obsolete.


    Installation

    Start by enabling it in your studio:

    sanity install conditional-field
    // or:
    yarn install conditional-field
    

    Usage

    You can use the ConditionalField component as the inputComponent of whatever field you want to conditionally render:

    import ConditionalField from 'sanity-plugin-conditional-field'
    
    export default {
      title: 'Article',
      name: 'article',
      type: 'document',
      fields: [
        {
          name: 'internal',
          title: 'Is this article internal?',
          type: 'boolean',
          validation: (Rule) => Rule.required(),
        },
        {
          name: 'externalUrl',
          type: 'url',
          inputComponent: ConditionalField,
          options: {
            // Simple conditional based on top-level document value
            hide: ({ document }) => document.internal, // hide if internal article
          },
        },
      ],
    }

    Async conditions

    {
      name: 'content',
      title: 'Content',
      type: 'array',
      of: [
        {type: 'block'},
      ]
      inputComponent: ConditionalField,
      options: {
        // Asynchronous conditions
        hide: async ({ document }) => {
          if (document.internal) {
            return true
          }
    
          const isValidContent = await fetch(`/api/is-valid-content/${document.externalUrl}`)
          return isValidContent ?
        }
      }
    }

    Nested conditions

    Besides the current document, the hide function receives a parents array for accessing contextual data.

    It's ordered from closest parents to furthest, meaning parents[0] will always be the object the field is in, and parents[-1] will always be the full document. If the field is at the top-level of the document, parents[0] === document.

    Here's an example of it in practice - notice how the link object is nested under an array, which means parents[1] will return the array with all the links:

    {
      name: 'links',
      title: 'Links',
      type: 'array',
      of: [
        {
          name: 'link',
          title: 'Link',
          type: 'object',
          fields: [
            {
              name: 'external',
              title: "Links to external websites?",
              type: 'boolean',
            },
            {
              name: 'url',
              title: 'External URL',
              type: 'string',
              inputComponent: ConditionalField,
              options: {
                hide: ({ parents }) => {
                  // Parents array exposes the closest parents in order
                  // Hence, parents[0] is the current object's value
                  return parents[0].external
                },
              },
            },
            {
              name: 'internalLink',
              type: 'reference',
              to: [{ type: "page" }],
              inputComponent: ConditionalField,
              options: {
                hide: ({ parents }) => !parents[0].external
              },
            },
            {
              name: 'flashyLooks',
              type: 'boolean',
              inputComponent: ConditionalField,
              options: {
                // Prevent editors from making the link flashy if this link is not in the first position in the array
                hide: ({ parents }) => ({
                  hidden: parents[1]?.indexOf(parents[0]) > 0 || false,
                  // Clear field's value if hidden - see below
                  clearOnHidden: true
                })
              },
            },
          ],
        },
      ],
    },

    Deleting values if field is hidden

    The hide function can also return an object to determine whether or not existing values should be cleared when the field is hidden. By default, this plugin won't clear values.

    {
      name: 'externalUrl',
      type: 'url',
      inputComponent: ConditionalField,
      options: {
        hide: ({ document }) => {
          hidden: !!document.internal,
          // Clear field's value if hidden
          clearOnHidden: true
        },
      },
    },

    Typescript definitions

    If you use Typescript in your schemas, here's how you type your hide functions:

    import { HideOption } from 'sanity-plugin-conditional-field'
    
    const hideBoolean: HideOption = false
    const hideFunction: HideOption = ({ document, parents }) => ({
      hidden: document._id.includes('drafts.') || parents.length > 2,
    })

    And here's the shape of the hide options:

    type ConditionReturn = boolean | { hidden: boolean; clearOnHidden?: boolean }
    
    export type HideFunction = (props: {
      document: SanityDocument
      parents: Parent[]
    }) => ConditionReturn | Promise<ConditionReturn>
    
    export type HideOption = boolean | HideFunction

    Shortcomings

    🚨 Big red alert: this plugin simply hides fields if conditions aren't met. It doesn't interfere with validation, meaning that if you set a conditioned field as required, editors won't be able to publish documents when it's hidden.

    Besides this, the following is true:

    • Async conditions aren't debounced, meaning they'll be fired a lot
    • There's no way of using this field with custom inputs

    Install

    npm i sanity-plugin-conditional-field

    DownloadsWeekly Downloads

    96

    Version

    1.0.0

    License

    Apache-2.0

    Unpacked Size

    16.1 kB

    Total Files

    9

    Last publish

    Collaborators

    • hdoro