How to use the conditional field

[NoelOConnell]

I'm looking to use the conditional field to show another field if a checkbox is checked.
I see that fields.conditional is available but not sure how to set it up.

[simonswiss]

Hey! First of all, sorry for the very late response.

The way the conditional field works is as follows. It lets you setup a discriminant for a condition that can be either a checkbox or a select field with a few options.

You can then display an entirely different set of fields based on the condition, by providing a key for each condition (true/false if you used a checkbox, and each possible value if you used a select.

Checkbox condition

Let's say you want to optionally display SEO title/description fields, but only if a user checks a checkbox.

Let's setup the following field in our schema:

seo: fields.conditional(
  // First, we define a checkbox to drive the yes/no condition
  fields.checkbox({ label: 'Define custom SEO tags', defaultValue: false }),
  // Then, we provide a set of fields for both the `true` and `false` scenarios
  {
    true: fields.object({
      title: fields.text({ label: 'Title' }),
      description: fields.text({ label: 'Description' }),
    }),
    // Empty fields are useful to show... no fields!
    false: fields.empty(),
  }
),

Here's what the Admin UI will look like with the checkbox checked or unchecked:

Select condition

Take this more complex example I used last week, where you have an optional Featured media field for an entry. The options for it are none, image and video.

Here's what the config for this field would look like:

// Featured media
featuredMedia: fields.conditional(
  // First, define a `select` field with all the available "conditions"
  fields.select({
    label: 'Featured media',
    description: 'Optional image/video options for an optional hero media.',
    options: [
      { label: 'No media', value: 'none' },
      { label: 'Image', value: 'image' },
      { label: 'Video', value: 'video' },
    ],
    defaultValue: 'none',
  }),
  // Then, provide a schema for each condition
  {
    // "none" condition
    none: fields.empty(),
    // "image" condition
    image: fields.object({
      asset: fields.image({
        label: 'Image',
        directory: 'public/images/events',
        publicPath: '/images/events/',
        validation: { isRequired: true },
      }),
      alt: fields.text({ label: 'Alt', description: 'Image alt text.' }),
    }),
    // "video" condition
    video: fields.object({
      url: fields.text({
        label: 'A YouTube video URL.',
        validation: { length: { min: 1 } },
      }),
      image: fields.object({
        asset: fields.image({
          label: 'Image',
          description: 'Thumbnail image override for the video.',
          directory: 'public/images/events',
          publicPath: '/images/events/',
        }),
        alt: fields.text({ label: 'Alt', description: 'Image alt text.' }),
      }),
    }),
  }
),

If you're using a checkbox, you'd have a condition for true and false, instead of none, image and video like in my example.

Hopefully it makes sense!

The Admin UI will only ever show (and expect according data entry) for the schema defined for the currently selected condition.

With the example code above, you'd get the scenarios shown in the screenshots below.

Hope it helps!

[NoelOConnell]

Hi Simon, thanks for the answer.
It makes perfect sense now and it will be very useful going forward.

[simonswiss]

Awesome, glad it was useful. And I promise we'll respond faster next time around 😅