You have found your way to the home of the VA Forms Library, where forms are created and enhanced for our customers across the country.
This is technical documentation meant to serve as a reference for software engineers working on the platform. If you're interested in reading more about the initial process of moving a paper form online, and the content design behind it, check out Getting Started with VA.gov Forms
What is the VA Forms Library?
The VA Forms Library is a comprehensive system that provides an easy to use and consistent way of creating complex forms for Veterans. Applications using forms that are created with the Forms Library are created with this general flow:
Introduction Page → Form Pages Start → Form Pages → Review Page → Submission → Confirmation Page
The Forms Library consists of several different pieces:
Standardized inputs and field sets for common types of form data
Validation functions used for commonly collected types of data
A standardized data flow within the application that triggers validation and updates conditionally displayed UI
Hooks for custom validation, hiding/showing fields, and writing custom fields and widgets
Save and restore form data using the save in progress and pre-fill APIs
If you'd like a deeper look into “What is the Forms Library” you can take a look at this audit for details about definitions, functions, widgets and more of the Forms Library. Current Forms Library Audit: Features, definitions, components, fields
What does the Forms Library do?
The Forms Library uses the Yeoman generator script (Yeoman Generator) and allows all files to be created and inserted inside of vets-website project under an application directory. This will also alter the local content-build repo and add an entry to the registry.json file so vets-website knows where your new application is located and how to display it.
The underlying technology of the Forms Library is React JsonSchema Form, and using this framework allows for specifying a “schema” and a “uiSchema” in a single form config file (JSON). This is great for consistency, speed of building, and general ease of use. If you'd like to learn more about these different options go here: Forms Library - About schema and uiSchema
How the Forms Library uses React Json Schema Form (RJSF)
The Forms Library code uses the form config to determine which React components to render to build your form, usually automatically. React components require props to render properly. These are passed down through the top-level
Formcomponent, which takes the entire form config itself as a prop. The
Formcomponent is also connected to the store, so it can access to the form data as well.
Why is the Forms Library set up using RJSF?
In January of 2017, there were a number of paper forms that needed to be digitized. Teams started researching different tools to easily convert these forms without too much overhead on Engineers and Designers. See the Decision Doc for Using RJSF page for the full history of this effort.
What was found was RJSF, and this solution was chosen because of a few factors:
Almost all form specific information is in a single configuration file, and has less boilerplate than building forms with React components.
There's very little form-specific React code. Most form specific-code are files that export configuration information, which is easy to modify and overwrite when necessary.
Forms are built using a JSON Schema file as a base and the backend uses the same file to validate submissions. So we're less likely to have schema errors than previously.
Building the config files is generally faster than building React components for each form.
Once RJSF was chosen, it was very fast to digitize the required OMB paper forms and get them deployed quickly and efficiently. As with all good systems, this came with some challenges and some customization that needed to be implemented. After a certain amount of customization was implemented, the team decided to “fork” the version of RJSF to eliminate upgrade breakages:
Switched JSON Schema validators from jsonschema to ajv. The ajv validator is faster and has more detailed error output, but is also much larger. It nearly doubles the size of RJSF. There haven’t been any major issues with jsonschema, and one of our goals is to reduce the bundle size of our forms.
Moved defaulting logic out of widgets. This means that all widgets now get form data with empty records, which is contrary to how they were written. It makes it harder to determine when a field is actually empty vs. just defaulted.
Maintains internal state for form data. This is not new, but it causes autofill bugs because rapid onChange events can cause stale data to overwrite the current form info. This is a design choice, so it's not really a bug to fix in the current library.
When should the Forms Library be used?
To determine when to use the Forms Library please refer to the What is a Form page, which describes what a “Form” is inside of the Forms Library.
A Form in the Forms Library should follow this general guideline:
Can accept data
Can submit data
With the expectation that you’re getting something in return
In a linear workflow with a clear start and end
At least one piece of data is required to submit it
That data goes somewhere
Is saved for later
To be used through a workflow, review, or approval process
To receive sort of response
1:1 correlation to an OMB number
(office of management & budget, as a consumer of gov’t services, it shows it’s official)
Not all forms, for example VHA forms, will have an OMB#
Can be only submitted once
Some forms allow editing after the fact, but it resubmits the data
When you must re-submit a form, that sends it through a workflow, review, or approval process again
Submitter acknowledgement of how the submitted data will be used
When to use the Design System instead of the Forms Library?
After reviewing the What is a Form page and determining that your use case does NOT fit the definition of a form (ex. Search bars, login pages, CRUD, etc), then we suggest you take a look into the Design System elements and components to see which of these could be useful. Here are some helpful links to get you started.
Forms Library Standards
Design.va.gov Form Feedback - Guidance on how error messaging is presented in forms
Design.va.gov Form Labels - Master list containing labels for form fields
Design.va.gov Form Confirmation Page - Guidance on what content should be presented on a form’s confirmation page
Design.va.gov CSS Utility Classes - Design system css classes that can be used in uiSchema
Forms Library Customizations
Inside of the Forms Library there are a ton of different ways to customize your form/application. A few of them can be referenced below by following the links.