How to use web component fields

This guide goes over how to use 'ui:webComponentField'.

The property 'ui:webComponentField' can be used in an RJSF form page uiSchema to tell it to use web components instead of the default widget behavior. Surrounding uiSchema properties/options will mostly work exactly the same as if you didn't include 'ui:webComponentField', however using JSX for a title or description may not always be supported.

Terminology

• Web component field - An implementation of a VADS web component that enables its use in a RJSF digitized form. It is an entire field including the error, title (label), description, input, help text. When the VADS updates a web component, the forms library version is also automatically updated. Note: it is recommended to use forms library web component patterns when possible as they leverage standardized validation, labels, form data, etc.

• Web component - Web components are a type of component created by the VA.gov Design System. They are interactive and non-interactive UI elements that can be grouped together or presented individually. They are independent, reusable chunks of a user interface. More information can be found here.

• Forms library web component pattern - An implementation of a VADS pattern that utilizes one or more forms library web component field(s) that enables its use in a digitized form. They feature standardized validation, labels, fields, and more and include an importable uiSchema and schema

• Forms library widget - The original method of rendering a field in react-jsonschema-form (what the forms library is forked from) that utilizes native React elements and USWDS stylings. These have been deprecated in favor of the web component fields due to multiple factors including maintainability, reusability, and accessibility factors

• Shadow DOM - the isolated nested HTML inside a web component

• USWDS = United States Web Design System

• v3 web component - uswds={true} passed to a web component

• v1 web component - usdws={false} or omitted from a web component

• VADS - VA Design System (team)

• DST = Design System team = VADS

• RJSF = React JSON Schema Form

Before you begin

Favor using web component patterns instead of manually specifying 'ui:webComponentField'.

Step 1: Adding 'ui:webComponentField'

To most existing RJSF code, you can add this property to make it into a web component:

Before:

simpleText: {
    'ui:title': 'TextWidget - with string description',
    'ui:description': 'Text description',
},

After:

import VaTextInputField from 'platform/forms-system/src/js/web-component-fields/VaTextInputField';

simpleText: {
    'ui:title': 'TextWidget - with string description',
    'ui:description': 'Text description',
    'ui:webComponentField': VaTextInputField
}

Before:

selectCustom: {
      'ui:title': 'Custom select',
      'ui:description': 'description',
      'ui:options': {
        labels: {
          option1: 'Option 1',
          option2: 'Option 2',
        },
      },
    },

After:

import VaSelectField from 'platform/forms-system/src/js/web-component-fields/VaSelectField';

selectCustom: {
      'ui:title': 'Custom select',
      'ui:webComponentField': VaSelectField,
      'ui:description': 'description',
      'ui:options': {
        labels: {
          option1: 'Option 1',
          option2: 'Option 2',
        },
      },
    }

See https://github.com/department-of-veterans-affairs/vets-website/tree/main/src/platform/forms-system/src/js/web-component-fields - Connect your Github account for all existing field mappings

For examples of all ui:options, see uiSchema options.

See How to use web component patterns for pattern usage

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.