Introduction

While using the Forms Library, there are going to be times when certain pages and chapters will not be relevant to certain users. This is when hiding and showing pages based on automatic criteria can be used to help.

The formConfig object has a special key called depends, which can be represented as an object, a list, or a function that’s passed the formData in which all properties, chapters, pages, etc. are stored. Having this information makes it easy to conditionally toggle the display of pages. Let’s take a look at some examples below.

// With an object
depends: {
  passPhrase: 'open sesame'
}

// With an array
// This will activate the page if any of the items in the array are true. Think || not &&.
depends: [
  { passPhrase: 'open sesame' },
  { passPhrase: 'open up!' }
]

// With a function
depends: (formData) => {
  // return bool, true if page is active, false if page should be skipped
  return formData.passPhrase === 'open sesame' && formData.codeWord === 'chicken';
}
JS

Conditionally Hide Page

In this test example, we'll use a passPhrase that determines whether or not to show the next page. This will be using depends as an Object with the key that matches the property from the first page. By passing the super secret pass phrase open sesame, the second page will show.

chapter1: {
  title: 'Chapter 1',
  pages: {
    page1: {
      path: 'first-page',
      title: 'First Page',
      uiSchema: {
        passPhrase: {
          'ui:title': 'Pass Phrase',
        },
      },
      schema: {
        type: 'object',
        properties: {
          passPhrase: { type: 'string' },
        },
      },
    },
    page2: {
      path: 'second-page',
      title: 'Second Page',
      depends: {
        passPhrase: 'open sesame',
      },
      uiSchema: {
        coolField: {
          'ui:title': 'Cool Conditional Page',
        },
      },
      schema: {
        type: 'object',
        properties: {
          coolField: { type: 'string' },
        },
      },
    },
  },
},
JS

Here is a screen movie from a live example of the code above, using the depends object with properties:


Now let’s try the same thing, but this time let’s set up the function and pass the formData into it.

chapter1: {
  title: 'Chapter 1',
  pages: {
    page1: {
      path: 'first-page',
      title: 'First Page',
      uiSchema: {
        passPhrase: {
          'ui:title': 'Pass Phrase',
        },
      },
      schema: {
        type: 'object',
        properties: {
          passPhrase: { type: 'string' },
        },
      },
    },
    page2: {
      path: 'second-page',
      title: 'Second Page',
      depends: formData => {
        return formData.passPhrase === 'open sesame';
      },
      uiSchema: {
        coolField: {
          'ui:title': 'Cool Conditional Page',
        },
      },
      schema: {
        type: 'object',
        properties: {
          coolField: { type: 'string' },
        },
      },
    },
  },
},
JS

Here is a screen movie from a live example of the code above, using function and formData:

Conditionally Hide Chapter

The depends key can also be applied to the Chapter level, which is useful when the formData is constantly getting updated in a long complex form. Below you'll see the code snippet from the Caregivers application; this snippet shows how to conditionally toggle the SecondaryCaregiversTwoChapter object of this formConfig Object.

Example 1: Caregivers formConfig Depends Chapter

{  
  ...
  secondaryCaregiversTwoChapter: {
    title: secondaryTwoChapterTitle,
    depends: formData => hasSecondaryCaregiverTwo(formData),
    pages: {
      secondaryCaregiverTwo: {
        path: 'secondary-two-1',
        title: secondaryTwoChapterTitle,
        depends: formData => hasSecondaryCaregiverTwo(formData),
        uiSchema: secondaryTwoInfoPage.uiSchema,
        schema: secondaryTwoInfoPage.schema,
      },
      secondaryCaregiverTwoTwo: {
        path: 'secondary-two-2',
        title: secondaryTwoChapterTitle,
        depends: formData => hasSecondaryCaregiverTwo(formData),
        uiSchema: secondaryTwoContactPage.uiSchema,
        schema: secondaryTwoContactPage.schema,
      },
    },
  },
  ...
}
JS

Now let’s see that code in action:

Example 2: Coronavirus-vaccination-expansion Form Config

This example shows a simpler example of conditionally hiding the page vaLocation within the vaLocation chapter:

chapters: {
  ...
  vaLocation: {
    title: 'Select where to go for your vaccine',
    pages: {
      vaLocation: {
        depends: formData => !isTypeNone(formData),
        path: 'vaccine-location',
        schema: vaLocation.schema.vaLocation,
        uiSchema: vaLocation.uiSchema.vaLocation,
      },
    },
  },
} 
JS