VA Forms Library - How to replace a form page using a feature toggle
Last Updated: February 27, 2025
When a form page requires significant changes, this guide outlines a recommended approach using a feature toggle to handle the transition. This pattern ensures smooth navigation and redirects users' save-in-progress data to the correct page.
Form library limitations
This pattern was developed after testing multiple approaches. Below are the key form library limitations that influenced the chosen method.
Issue: Duplicate Path Handling
Problem: A repeated path is ignored and may break navigation. If you attempt to add a new page alongside the original and use depends (saved to form data) to toggle visibility, the form system will not navigate correctly to the second page.
Example:
// appName/config/form.js
newPage: {
title: 'new page',
path: 'page-path',
depends: formData => formData[TOGGLE_KEY],
// ...
},
currentPage: {
title: 'current page',
path: 'page-path', // Form system will ignore duplicate paths
depends: formData => !formData[TOGGLE_KEY],
// ...
},Issue: Displaying a New Entry on an Existing Page
Problem: The scope of form data is limited to individual components, making it difficult to use the same form data key for both sections. Additionally, arrayPath does not work for array pages.
Solution: Use hideIf (saved to form data) to toggle content visibility.
Example:
// appName/config/form.js
currentPage: {
uiSchema: {
newComponent: {
'ui:options': {
hideIf: formData => formData[TOGGLE_KEY],
},
},
currentComponent: {
'ui:options': {
hideIf: formData => !formData[TOGGLE_KEY],
},
},
},
},Issue: Dynamically Rendering a Page
Problem: Using traditional uiSchema, the schema is set only when the form initializes. Dynamically rendering a page based on a toggle stored in session storage may work but is not fully tested.
Example:
// appName/config/form.js
currentPage:
sessionStorage.getItem(TOGGLE_KEY)
? newComponent
: currentComponent, Using web components, you can dynamically update the schema using upadateUiSchema and/or updateSchema.
Example:
// appName/config/form.js
const formConfig = {
currentPage: {
uiSchema: {
test: yesNoUI({
...radioOptions,
updateUiSchema: formData =>
formData[TOGGLE_KEY] ? selectUI(selectOptions) : yesNoUI(radioOptions),
}),
},
},
};Issue: Form Redirects Using Migrations
Problem: Form migrations are not ideal for feature toggles because they only run when the save-in-progress metadata version changes. This means you would need to manually update the migrations logic each time you adjust the feature toggle percentage
Example:
// appName/config/form.js
const migrations = [
progressData => progressData, // Initial migration (no changes)
({ formData, metadata }) => {
const pagesBefore = ['/page1', '/page2', '/page3'];
const returnUrl = !pagesBefore.includes(metadata.returnUrl)
? '/new-page-url' // Redirect user
: metadata.returnUrl; // No change
return { formData, metadata: { ...metadata, returnUrl } };
},
];
const formConfig = {
version: migrations.length,
migrations,
};Before you begin
Ensure the following before implementing this pattern:
Your team plans a stepped rollout of the new page.
The update involves more than minor content changes (use Toggler for content-only changes).
A feature toggle is set up for the new content.
Step-by-step guide
Step 1: Save the Toggle Value
Use the useFormFeatureToggleSync hook to add the feature toggle value into form data and session storage.
Usage Example:
// appName/container/App.jsx
import { useFeatureToggle } from 'platform/utilities/feature-toggles';
// ... inside App function ...
const TOGGLE_KEY = 'featureToggleName';
const { useFormFeatureToggleSync } = useFeatureToggle();
useFormFeatureToggleSync([
// Feature toggle name & form data key will be the same
'featureToggleNameAndDataKey',
{
toggleName: TOGGLE_KEY, // feature toggle name
formKey: 'toggleNameInFormData' // form data name
},
]);If you don’t want to use the above hook, add the following code in your main app file:
Feature Toggle Hook:
// appName/container/App.jsx
const TOGGLE_KEY = 'featureToggleName';
const {
TOGGLE_NAMES,
useToggleValue,
useToggleLoadingValue,
} = useFeatureToggle();
const newFormDataEnabled = useToggleValue(TOGGLE_NAMES[TOGGLE_KEY]);
const isLoadingFeatureFlags = useToggleLoadingValue();
useEffect(
() => {
if (!isLoadingFeatureFlags && formData[TOGGLE_KEY] !== newFormDataEnabled) {
setFormData({
...formData,
[TOGGLE_KEY]: newFormDataEnabled,
});
// optional - use for functions that don't have access to
// form data
sessionStorage.setItem[TOGGLE_KEY] = newFormDataEnabled;
}
},
// eslint-disable-next-line react-hooks/exhaustive-deps
[isLoadingFeatureFlags, newFormDataEnabled, formData[TOGGLE_KEY]],
);
Step 2: Add the new page form config
Place the new page before or after the existing page. The new page should inherit the current URL, while the existing page gets a deprecated path.
Example:
// appName/config/form.js
const PATH_CURRENT = 'page-path';
const PATH_DEPRECATED = 'page-path-deprecated';
const formConfig = {
newPage: {
title: 'New Page',
path: PATH_CURRENT,
depends: formData => formData[TOGGLE_KEY],
},
currentPage: {
title: 'Current Page',
path: PATH_DEPRECATED,
depends: formData => !formData[TOGGLE_KEY],
},
};Step 3: Handle save-in-progress redirects
Ensure users return to the correct page if they resume the form after a toggle update.
Example:
// appName/config/form.js
onFormLoaded: ({ formData, returnUrl, router }) => {
const pagesBefore = ['/page1', '/page2', '/page3', `/${PATH_DEPRECATED}`];
if (formData[TOGGLE_KEY] && !pagesBefore.includes(returnUrl)) {
router?.push(`/${PATH_CURRENT}`);
} else if (!formData[TOGGLE_KEY] && returnUrl === `/${PATH_CURRENT}`) {
router?.push(`/${PATH_DEPRECATED}`);
} else {
router?.push(returnUrl);
}
};Once the new page is fully released, remove the deprecated page from the form config, but keep the onFormLoaded redirect until save-in-progress data expires, typically 60 days or 1 year for some forms.
Help and feedback
Get help from the Platform Support Team in Slack.
Submit a feature idea to the Platform.