Improving the Accessibility of the WPForms Progress Bar

Do you use multi page forms and want the progress bar and section headings to pass more accessibility checks? Some scanners report issues such as missing accessible names on the progress bar and skipped heading levels inside divider fields.

In this tutorial, we will show you how to add a custom JavaScript snippet that:

• Adds an aria-label to the progress bar
• Changes section divider headings from h3 to h2 to improve heading hierarchy

Before You Begin

This tutorial is designed for multi page forms that:

• Use the progress bar style page indicator
• Include Divider fields that output headings inside the form

You will also need a way to add custom PHP to your site, such as a site specific plugin or a snippets plugin.

If you need help adding custom code, please see our guide on how to add custom PHP snippets for WPForms.

Adding the Accessibility Fix Snippet

To add the accessibility improvements, use the code snippet below. It prints a small script into your site footer that updates the progress bar and section divider headings on the front end.

After saving the snippet, open a page that contains your multi page form and verify that the progress bar still works as expected.

How the Snippet Works

The first function adds an aria-label to each element with the wpforms-page-indicator progress classes so the progress bar has an accessible name. The second function finds h3 headings inside divider fields, recreates them as h2 elements with the same attributes and content, and replaces the originals to improve heading hierarchy.

Customizing the Snippet

You can adjust the snippet to better match your site.

Change the aria label text

Inside the first script block, update this line:

$(this).attr('aria-label', 'Form Page Progress');

Change the text in quotes to a label that makes sense for your form, such as:

$(this).attr('aria-label', 'Graduation application progress');

This is the text that screen readers will announce for the progress bar.

Target a specific form only

By default, the selectors:

$('.wpforms-page-indicator.progress')
$('.wpforms-field-divider h3')

apply to every WPForms progress bar and divider on your site.

If you want to limit this behavior to a single form, you can add the form’s ID to the selector. For example, for form ID 123:

$('#wpforms-123 .wpforms-page-indicator.progress')
$('#wpforms-123 .wpforms-field-divider h3')

This keeps the changes scoped to that form only.

That’s it, now you’ve learned how to give your multi page forms a more accessible progress bar and heading structure using a custom JavaScript snippet.

Next, you may want to review our guide on creating multi page forms in WPForms to see all the options for configuring page breaks and progress indicators