VA Forms Library - How to hide pages and chapters in a form

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.

JS

// 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';
}

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.

JS

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' },
        },
      },
    },
  },
},

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

Live example showing the correct pass phrase of open sesame, which then displays the second page of the form

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

JS

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' },
        },
      },
    },
  },
},

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

Live example showing the correct pass phrase of open sesame, which then displays the second page of the form 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

JS

{  
  ...
  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,
      },
    },
  },
  ...
}

Now let’s see that code in action:

Depends on Chapter for Secondary Caregivers where yes takes you to another form and no takes you to the signature page

Example 2: Coronavirus-vaccination-expansion Form Config

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

JS

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,
      },
    },
  },
}

Help and feedback

Suggest content changes to this page.
Submit new Platform Website content.
Get help from the Platform Support Team in Slack.
Submit a feature idea to the Platform.