Skip to main content
Skip table of contents

VA Forms Library - Web components in RJSF

This page documents information related to web component adoption by forms teams, using ui:webComponentField in RJSF, including status, how to adopt, decisions, and defects

Status

Related Epic

https://app.zenhub.com/workspaces/vagov-product-team-forms-634853151f5c6000165942bc/issues/gh/department-of-veterans-affairs/va.gov-team/54747

Decisions

  • Late March 2023 - We will inject the web component at the field template level rather than the widget level, So that the web component can own the entire field including the error, and we just pass it all the information. (widgets are only the input area and accept different props than the field, and would feel like an incomplete adoption of web components)

  • April 2023 - We will unit test by verifying at the va-web-component level rather than the shadowRoot level, due to shadow root being difficult to test. Cypress however can test the shadow root.

  • Late April 2023 - We will use v3 of the web components, which is usdws: true. There are many issues with v1 web components, that v3 solves, and it will better align with both DST + forms team's timeline to work on v3 at the same time to find the issues.

How to use

Web component fields

To any existing uiSchema, include the property 'ui:webComponentField' with a component from platform/forms-system/src/js/web-component-fields/:

CODE 
uiSchema: {
	...existing fields
	'ui:webComponentField': VaRadioField,
}

// other examples
'ui:webComponentField': VaTextInputField,
'ui:webComponentField': VaSelectField,
'ui:webComponentField': VaCheckboxField,
etc...

You should be able to change most existing schemas to the web component version simply by adding the 'ui:webComponentField'.

Important: Do not use the React binding version component directly in this field property.

Example: VaTextInputField is not the same thing VaTextInput. The field contains extra mapping to translate RJSF properties to the React binding version of the web component.

Other notes

'ui:widget' will not affect the input of the web component field, because the logic is shortcutted in src/js/components/FieldTemplate.jsx. However 'ui:widget' will still affect how the review page is displayed.

Web components may display description or title differently and may not accept HTML. This is by design. Some web components do not accept a description.

Check storybook to see properties of web components: https://design.va.gov/storybook/?path=/docs/components-va-text-input--default

Web component patterns

Instead of using 'ui:webComponentField', you can use some predefined patterns from platform/forms-system/src/js/web-component-patterns/, which are similar to existing definitions we have today:

CODE 
import {
  dateOfBirthSchema,
  dateOfBirthUI,
  emailSchema,
  emailUI,
  fullNameSchema,
  fullNameUI,
  phoneSchema,
  phoneUI,
  ssnOrVaFileNumberOrServiceNumberSchema,
  ssnOrVaFileNumberOrServiceNumberUI,
} from 'platform/forms-system/src/js/web-component-patterns';

return default {
  uiSchema: {
    fullName: fullNameUI()
  },
  schema: {
    type: 'object',
    properties: {
      fullName: fullNameSchema
    }
  }

Patterns come in pairs:

  • patternUI() function

  • patternSchema object.

Patterns may not exactly match the prior non-web-component versions, so check usage by hovering the functions.

Defects

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close