VA Forms Library - Form Config Options
Last Updated:
To create the form/application using the Forms Library, we need to set up the form's configuration. The application code uses the Form Config to determine which React components to render to build the form. We can also customize the form through this configuration.
Here is a list of form configuration options available.
Options | Value Type | Description | Example |
---|---|---|---|
rootUrl | string | Application directory. |
|
urlPrefix | string | Prefix string to add to the path for each page. |
|
introduction | component | The introduction page component. To exclude an introduction page, remove this component. |
|
confirmation | component | The confirmation page component that will render after the user successfully submits the form. |
|
trackingPrefix | string | The prefix for Google Analytics events that are sent for different form actions. |
|
title | string or function | The title of the form, rendered on all pages. Accepts a string or function; params include (currentLocation, formConfig, formData, children). |
or
|
subTitle | string or function | The subtitle of the form, usually the form number. The subtitle is rendered on all pages when there's also a title. Accepts a string or function; params include (currentLocation, formConfig, formData, children). |
|
defaultDefinitions | object | Schema definitions that can be referenced on any page. These are added to each page's schema in the reducer code, so that you don't have to put all of the common fields in the definitions property in each page schema. For more information on definitions, see the VA Forms Library - About schema and uiSchema page. |
|
prefillTransformer | function | When a user begins completing a pre-filled form, this function is called after data migrations are run for pre-filled data to make necessary updates to the data or form schema ahead of time. |
|
migrations | array | An array of functions that are applied during a form's lifecycle. The number of migration functions should be equal to the version. For example, there are two migration functions in 21P-530 Form. The version of this form is '2.' |
|
version | number | Indicates the version of a form, this should be increased by one when a migration is required. |
|
submitUrl | string | Path to vets-api controller for form submission. |
|
submit | function | Function that’s called upon form submission. Optional: If a custom submit isn’t provided, there’s a system default that runs. |
|
transformForSubmit | function | Called during form submission to transform submitted schema data (Optional). Calling transformForSubmit in platform/forms-system/src/js/helpers will remove view fields from the schema data. |
|
errorText | component | Component used as part of the default error message if submission of the form fails. |
|
submissionError | function | Component that replaces the default error message component if submission of the form fails. |
|
object | See the savedFormMessages section. | ||
wizardStorageKey | string | Defaults to WIZARD_STATUS in 'platform/site-wide/wizard'. Added here if your form uses a unique sessionStorage key (currently only used by the save-in-progress component). |
|
object | Contains the Save in Progress (SiP) configuration. See the saveInProgress section. | ||
prefillEnabled | boolean | Enables prefill. |
|
object | See the downtime section. | ||
verifyRequiredPrefill | boolean | Verify the required pre-filled information is available to show on the form. |
|
object | Additional information to be displayed on the Review page. See platform/forms/preSubmitInfo for the standard object. |
| |
footerContent | component | Content to be displayed at bottom of a form, see platform/forms/components/FormFooter for the standard object. |
|
getHelp | component | Component that’s displayed as part of standard footerContent property. |
|
onFormLoaded | function | Function called during the loading of a form. |
|
formSavedPage | component | Component displayed when a form has been saved. If not provided, platform/forms/save-in-progress/FormSaved.jsx is used instead. |
|
array | Provides additional routes that are not found within the page lists. Introduction and review-and-submit pages are added in automatically. | ||
object | Custom text values that will be used throughout a form. | ||
object | The object that contains the configuration for each chapter. | ||
intentToFileUrl | string | Deprecated properties still in use in applications/disability-benefits/all-claims/config/form.js. |
|
submitErrorText | component | Deprecated properties still in use in applications/hca/config/form.js. |
|
showReviewErrors | boolean | Show error links on the review page. |
|
ariaDescribedBySubmit | string | This identifies the element that describes the element on which the attribute is set. |
|
savedFormMessages
Messages to be sent to the Save-in-Progress (SiP) component.
Properties | Value Type | Example |
---|---|---|
notFound | string |
|
noAuth | string |
|
forbidden | string |
|
savedFormMessages examples
From the 22-0993 Education Benefits Form:
savedFormMessages: {
notFound:
'Please start over to apply to opt out of sharing VA education benefits information.',
noAuth:
'Please sign in again to continue your application to opt out of sharing VA education benefits information.',
},
savedFormMessages is typically passed into a SaveInProgressIntro component in the form's introduction container. In the example below, this is passed into the property "messages".
From the COVID-VACCINE-TRIAL Introduction page:
<SaveInProgressIntro
prefillEnabled={this.props.route.formConfig.prefillEnabled}
messages={this.props.route.formConfig.savedFormMessages}
pageList={this.props.route.pageList}
startText="Volunteer for COVID-19 research"
>
Please complete the 12345 form to apply for vaccine trial
participation.
</SaveInProgressIntro>
saveInProgress
This is the configuration for setting the status messages, callback, and resume form.
Properties | Value Type | Description |
---|---|---|
messages | object | These messages will be displayed as-is when appropriate. |
restartFormCallback | function | Form restart-specific options. This callback is only called by the RoutedSavableApp, so if the wizard is being rendered by the outer form App file, this callback won't work. If the wizard is being rendered within the Intro page (like 0996 HLR), then have the function return a destination route ('/' is the introduction page). |
resumeOnly | boolean | The configuration for hiding the "start a new app" button on the form saved page. Users cannot restart a form once started. |
messages
This is the message object of saveInProgress. It contains the status of the saved information on the form.
Properties | Value Type | Example |
---|---|---|
inProgress | string |
|
expired | string |
|
saved | string |
|
saveInProgress example
From the 20-0996 Disability Benefits Form:
saveInProgress: {
messages: {
inProgress:
'Your Higher-Level Review application (20-0996) is in progress.',
expired:
'Your saved Higher-Level Review application (20-0996) has expired. If you want to apply for Higher-Level Review, please start a new application.',
saved: 'Your Higher-Level Review application has been saved.',
},
// return restart destination url
restartFormCallback: () => '/', // introduction page
},
downtime
A list of services that correspond to those for which there is downtime information provided by the API. The full list of services can be found in platform/monitoring/DowntimeNotification/config.
Properties | Value Type | Example |
---|---|---|
requiredForPrefill | boolean |
|
dependencies | array |
|
message | string |
|
downtime example
From the 10182 Appeals Form:
downtime: {
requiredForPrefill: true,
dependencies: [
services.vaProfile,
services.bgs
services.mvi,
services.appeals,
],
},
customText
Custom text values that will be used throughout a form.
Properties | Value Type | Example |
---|---|---|
reviewPageTitle | string |
|
appSavedSuccessfullyMessage | string |
|
startNewAppButtonText | string |
|
continueAppButtonText | string |
|
finishAppLaterMessage | string |
|
appType | string |
|
appAction | string |
|
submitButtonText | string |
|
appContinuing | string |
|
customText examples
From the MDOT Form:
customText: {
reviewPageTitle: 'Review order details',
appSavedSuccessfullyMessage: 'Order has been saved.',
startNewAppButtonText: 'Start a new order',
continueAppButtonText: 'Continue your order',
finishAppLaterMessage: 'Finish this order later.',
appType: 'order',
appAction: 'placing your order',
}
From the COE (Certificate of Eligibility) Form:
customText: {
appAction: 'your COE request',
appSavedSuccessfullyMessage: 'Your request has been saved.',
appType: 'request',
continueAppButtonText: 'Continue your request',
finishAppLaterMessage: 'Finish this request later',
startNewAppButtonText: 'Start a new request',
reviewPageTitle: 'Review your request',
},
preSubmitInfo
Additional information to be displayed on the Review page. See platform/forms/preSubmitInfo for the standard object.
Properties | Value Type | Example |
---|---|---|
required | boolean |
|
field | string |
|
notice | string |
|
label | string |
|
error | string |
|
CustomComponent | component |
|
statementOfTruth | object |
|
heading | string |
CODE
|
body | string |
CODE
|
messageAriaDescribedby | string |
CODE
Usually, this should be the same as |
textInputLabel | string |
CODE
|
checkboxLabel | string |
CODE
|
fullNamePath | string |
CODE
|
preSubmitInfo examples
From the 22-0994 Education Benefits Form:
preSubmitInfo: {
CustomComponent: PreSubmitInfo,
required: true,
field: 'privacyAgreementAccepted',
},
From the COVID-VACCINE-TRIAL Form:
preSubmitInfo: {
required: true,
field: 'consentAgreementAccepted',
label: ConsentLabel(),
notice: ConsentNotice(),
error: ConsentError(),
},
additionalRoutes
Provides additional routes that are not found within the page lists. It contains array of additional route objects.
Properties | Value Type | Example |
---|---|---|
path | string |
|
component | string |
|
pageKey | string |
|
depends | function |
|
additionalRoutes example
From the 1010ez Form:
additionalRoutes: [
{
path: 'id-form',
component: IDPage,
pageKey: 'id-form',
depends: () => !hasSession(),
},
],
chapters
The object that contains the configuration for each chapter. Each property is the key for a chapter.
Properties | Value Type | Example |
---|---|---|
title | string or function |
|
hideFormNavProgress (optional) | boolean |
|
object | ||
reviewDescription | object |
|
depends | boolean |
|
chapters example
From the 21-526EZ Disability Claim Form:
chapters: {
veteranDetails: {
title: isReviewPage => `${isReviewPage ? 'Review ' : ''}Veteran Details`,
pages: {...
},
disabilities: {
title: 'Disabilities',
pages: {...
},
supportingEvidence: {...
},
additionalInformation: {
title: 'Additional information',
pages: {...
},
},
pages
The object that contains the pages in each chapter. Each property is the key for a page, and should be unique across chapters.
Properties | Value Type | Description | Example |
---|---|---|---|
path | string | The URL for the page. |
|
title | string or function | The title of the page that renders on the review page. ‘title’ can also be a function that receives the current data as a parameter. |
|
initialData | object | Any initial data that should be set for the form. |
|
showPagePerItem | boolean | Specifies that a page will turn its schema into a page for each item in an array, such as an array of children with a page for each child. The schema/uiSchema for this type of page should be built as usual for an array field. |
|
depends | boolean | A dependency needed to show the page. |
|
arrayPath | string | The path to the array. |
|
itemFilter | boolean | Items in the array that should not have a page. |
|
hideHeaderRow | boolean | Hide header row. |
|
CustomPage | component | The custom page component will be rendered instead of using uiSchema. |
|
CustomPageReview | component | The custom review page component will be rendered instead of using uiSchema. |
|
onContinue | function | Capture the event when the user clicks "Continue" on the form. |
|
pageClass | string | Class for page stylesheet. |
|
schema | object | The JSON schema object for the page, following the JSON Schema format. | |
uiSchema | object | The JSON schema object for the user interface on the page, following the JSON Schema format. | |
boolean | Controls which fields are rendered on the review & submit page |
|
pages example
From the Education Benefits FEEDBACK-TOOL Form:
pages: {
applicantRelationship: {
path: 'applicant-relationship',
title: 'Applicant Relationship',
uiSchema: {...
},
schema: {...
},
},
applicantInformation: {
path: 'applicant-information',
title: 'Applicant Information',
depends: isNotAnonymous,
uiSchema: {...
},
schema: {...
},
},
serviceInformation: {
path: 'service-information',
title: 'Service Information',
depends: isVeteranOrServiceMember,
uiSchema: {...
},
schema: {...
},
},
contactInformation: {
path: 'contact-information',
title: 'Contact Information',
depends: formData => formData.onBehalfOf !== anonymous,
uiSchema: {...
},
schema: {...
},
},
},
Putting it together
This is a complete formConfig example from the 10182 Appeals Form:
const formConfig = {
rootUrl: manifest.rootUrl,
urlPrefix: '/',
submitUrl: `${environment.API_URL}/v0/notice_of_disagreements`,
trackingPrefix: '10182-board-appeal-',
downtime: {
requiredForPrefill: true,
dependencies: [
services.vaProfile,
services.bgs,
services.mvi,
services.appeals,
],
},
formId: VA_FORM_IDS.FORM_10182,
version: migrations.length - 1,
title: 'Request a Board Appeal',
subTitle: 'VA Form 10182 (Notice of Disagreement)',
prefillEnabled: true,
prefillTransformer,
verifyRequiredPrefill: true,
transformForSubmit: transform,
preSubmitInfo,
submit: submitForm,
// SaveInProgress messages
customText,
savedFormMessages,
saveInProgress,
// errorText: '',
// submissionError: '',
introduction: IntroductionPage,
confirmation: ConfirmationPage,
defaultDefinitions: {},
chapters: {
infoPages: {
title: 'Veteran details',
reviewDescription: ReviewDescription,
pages: {
veteranInformation: {
title: 'Veteran details',
path: 'veteran-details',
uiSchema: veteranInfo.uiSchema,
schema: veteranInfo.schema,
// initialData,
},
homeless: {
title: 'Homelessness question',
path: 'homeless',
uiSchema: homeless.uiSchema,
schema: homeless.schema,
},
contactInformation: {
title: 'Contact information',
path: 'contact-information',
uiSchema: contactInfo.uiSchema,
schema: contactInfo.schema,
},
},
},
conditions: {
title: 'Issues for review',
pages: {
contestableIssues: {
title: 'Issues eligible for review',
path: 'eligible-issues',
uiSchema: contestableIssues.uiSchema,
schema: contestableIssues.schema,
},
additionalIssuesIntro: {
title: 'Additional issues for review',
path: 'additional-issues-intro',
depends: showAddIssueQuestion,
uiSchema: additionalIssuesIntro.uiSchema,
schema: additionalIssuesIntro.schema,
appStateSelector,
},
additionalIssues: {
title: 'Add issues for review',
path: 'additional-issues',
depends: showAddIssuesPage,
uiSchema: additionalIssues.uiSchema,
schema: additionalIssues.schema,
appStateSelector,
},
areaOfDisagreementFollowUp: {
title: getIssueName,
path: 'area-of-disagreement/:index',
showPagePerItem: true,
arrayPath: 'areaOfDisagreement',
uiSchema: areaOfDisagreementFollowUp.uiSchema,
schema: areaOfDisagreementFollowUp.schema,
},
optIn: {
title: 'Opt in',
path: 'opt-in',
uiSchema: optIn.uiSchema,
schema: optIn.schema,
},
issueSummary: {
title: 'Issue summary',
path: 'issue-summary',
uiSchema: issueSummary.uiSchema,
schema: issueSummary.schema,
},
},
},
boardReview: {
title: 'Board review option',
pages: {
boardReviewOption: {
title: 'Board review option',
path: 'board-review-option',
uiSchema: boardReview.uiSchema,
schema: boardReview.schema,
},
evidenceIntro: {
title: 'Evidence submission',
path: 'evidence-submission',
depends: canUploadEvidence,
uiSchema: evidenceIntro.uiSchema,
schema: evidenceIntro.schema,
},
evidenceUpload: {
title: 'Evidence upload',
path: 'evidence-submission/upload',
depends: wantsToUploadEvidence,
uiSchema: evidenceUpload.uiSchema,
schema: evidenceUpload.schema,
},
hearingType: {
title: 'Hearing type',
path: 'hearing-type',
depends: needsHearingType,
uiSchema: hearingType.uiSchema,
schema: hearingType.schema,
},
},
},
},
footerContent: FormFooter,
getHelp: GetFormHelp,
};
export default formConfig;
Help and feedback
Get help from the Platform Support Team in Slack.
Submit a feature idea to the Platform.