Skip to main content Skip to footer

The Accessibility Benefits from Upgrading Umbraco


There are many benefits to an Umbraco upgrade, including:

However, an Umbraco upgrade doesn't just mean upgrading the core CMS functionality but also brings an upgrade to Umbraco Forms. For those who haven't worked with Umbraco, Umbraco Forms allows content editors to easily build responsive forms within Umbraco and generates HTML that can be easily added to Umbraco websites. 

Umbraco Forms and Accessibility Improvements

Alongside the performance and sustainability improvements provided by Umbraco CMS, the accessibility of the HTML generated by default from Umbraco Forms has also been improved.

In 2020, a cluster of leading authoring tools, including Umbraco, came together to improve accessibility by default in those authoring tools, with Nexer Digital representing Umbraco. Feedback from this project helped feed into some of the accessibility within Umbraco Forms. The Umbraco Community Accessibility Team, alongside the wider Umbraco Community, have also provided feedback to Umbraco to help improve accessibility.

This article explores some of the things we, as developers, can do to empower the authors using Umbraco Forms to create more accessible forms. With accessibility in Umbraco Forms being iteratively improved, each section will mention the earliest version of Umbraco Forms a feature has been implemented in.

Umbraco Forms Logo


A quick note on how Umbraco Forms terminology maps to HTML:

  • When a content author builds: a form they create a group of questions. This group of questions is a fieldset in html.
  • Each group of questions has a caption. This is the fieldset legend in html.
  • Each question has a name this will become the label and an answer type this is translated into various form controls.


From W3C Labelling Control Tutorial:

"A label for a form control helps everyone better understand its purpose. In some cases, the purpose may be clear enough from the context when the content is rendered visually. The label can be hidden visually, though it still needs to be provided within the code to support other forms of presentation and interaction, such as for screen reader and speech input users."

All form controls must be labelled, and the label must relate to the form field. When creating a form, the content editor selects the fields to add to the form.  The content editor must give these field a name, and this name becomes the label on the form.

Instructions should also be provided to help explain questions on the form; this can be done by using the help text property. From Umbraco Forms v10.5.0 the instructions have been linked to the input by using aria-describedby on the input.

Caution: It is possible to remove the label from the form by unchecking "show label" when editing the question; this will remove the field label both visually and for users of assistive technology, making the form non-compliant.


From W3C Form Instructions Tutorial

"Provide instructions to help users understand how to complete the form and use individual form controls. Indicate any required and optional input, data formats, and other relevant information."

Instructions should also be provided to help explain questions on the form; this can be done by using the help text property. From Umbraco Forms v10.5.0 the instructions have been linked to the input by using aria-describedby on the input.

HTML 5 Attributes


Auto complete was added in Umbraco Forms v8.8.

From w3schooles "Accessibility Autocomplete" the autocomplete attribute:

"makes a form easier and more efficient for all users, especially users that are attention deficit, have cognitive impairments, reduced mobility, low vision or blind users."

To enable autocomplete on a form:

  • On the form edit screen click the settings cog on the top right of the screen.
  • Scroll to Autocomplete and set it to "on".

To enable autocomplete on a field on a form:

  • Select the question for autocomplete to be enabled.
  • Select the cog on the question.
  • Scroll to "autocomplete attribute".
  • Type "on".

There are cases where setting autocomplete to on can be a security risk, such as for questions like "username" and "credit card".

From Umbraco Forms 10 the default value form autocomplete can be configured in the appsettings.json:

"Umbraco": {
    "Forms": {
      "Defaults": {
        "AutocompleteAttribute": "on"

Data Types

Support for HTML 5 attributes was added in Umbraco Forms v8.10

Using HTML 5 attributes helps accessibility from Deque "Accessible Client-side Form Validation with HTML5":

"HTML5 input types greatly enhance the usability and accessibility of forms on mobile devices. In iOS, the iPhone, iPad, & iPod Touch platform, most input types will display a keyboard enhanced for that data format. Input Types Add More Stringent Validation"

To use HTML 5 attributes in the edit question screen scroll to the field type and select the field type to use. The following HTML 5 attributes are supported on textboxes:

Where the browser doesn't support the various HTML 5 attributes detailed above the browser will degrade gracefully to be of text type.

Required Fields

In order to help with error prevention, and to make it easier for users to fill in the form, users should be made aware of all required fields as they file in the form.

This is normally done by labelling the field visibly as required:

  • If the form only contains optional fields then users can be advised of this at the start of the form.
  • If the form only contains required fields then users can be advised of this at the start of the form, however some users with cognitive impairments my be empowered by adding a required label on every field.
  • If the form contains a mix of required fields and optional fields then it is usual practice to mark the required fields. 

Umbraco Forms allows the required fields to be managed by:

  • Going to the settings for the form 
  • Scrolling to "Mark fields" (found in the Validation section)
  • Selecting either "Mark Mandatory Fields" or "Mark Optional Fields"
  • If selecting "Mark Optional Fields" change the indicator from "*" to "(Optional)" or similar.

From Umbraco 10 the default values for required fields can be managed via the appsettings.json:

"Umbraco": {
    "Forms": {
      "Defaults": {
        "MarkFieldsIndicator": "NoIndicator"

The MarkFieldsIndicator configuration value can have one of the following values:

  • NoIndicator - default.
  • MarkMandatoryFields - indicate the fields which are mandatory.
  • MarkOptionalFields - indicate the fields which are optional.

From Umbraco 10 the following can be configured in appsettings.json to change the default indicator of a field, from * to Required or Optional:

"Umbraco": {
    "Forms": {
      "Defaults": {
        "Indicator": "*"

Prior to Umbraco Forms v10.5.0 required fields were marked by an *, but read as "star". Umbraco Forms v.10.5.0 saw the introduction of HTML 5 markup required to indicate required fields.


Success criterion 3.3.1 states that:

"users are aware that an error has occurred and can determine what is wrong. In the case of an unsuccessful form submission, it is not sufficient to only re-display the form without providing any hint that the submission failed. The error must be indicated in text." 

A number of changes have been made to the mark up to ensure that users are notified of an error:

  • Focus - When an error occurs the form should bring the first validation error into focus. This has been available from Umbraco Forms v8.9.
  • Alert - When a validation message is present on the page, the screen reader gets an alert. This has been available from Umbraco Forms 10.5.0.

In form settings it is possible to select:

  • Show validation summary - this will show a summary of all errors at the top of the page. 
  • Hide field validation labels - this will hide the error messages next to fields. Checking this may mean that the form fails WCAG 2.2 standards, so if this field is checked an audit of the form to ensure is required to ensure that it still passes WCAG 2.2.

In Umbraco 10 it became possible to configure these values by default in appsettings.json:

"Umbraco": {
    "Forms": {
      "Defaults": {
        "ShowValidationSummary": false,
        "HideFieldValidationLabels": false


When a content editor adds a group of fields to an Umbraco form, the fields are wraped in <fieldset> in the markup. The caption for the content editor adds for the group becomes the <fieldset> legend.

Up until Umbraco Forms v.13.1.0, the caption was optional, meaning content authors could render fieldsets without a legend. To pass WCAG Criteria 1.3.1 Info and Relationships when a <fieldset> element is added into mark up then a legend should be added.

In order to pass this criterion prior to Umbraco Forms v13.1.0 the content author had to remember to enter a name for each field grouping. From Umbraco Forms v13.1.0 onwards can add the following to the appsettings.json to ensure that the content author adds a caption for the group.

"Umbraco": {
    "Forms": {
      "FormDesign": {
        "MandatoryFieldsetLegends": true

When MandatoryFieldsetLegends is set to true content authors are not able to save a form unless the fieldset legend, labelled in the form editor as the caption for the group is completed.

Checkboxes and Radio Options

Available from Umbraco Forms v10.5.0 and Umbraco From 12.1.

Radio options and checkbox groups should always be grouped in a <fieldset> for more information, please visit Grouping Controls. For backwards compatibility the setting for enabling this is in the appsettings.json

"Umbraco": {
    "Forms": {
      "Options": {
        "UseSemanticFieldsetRendering": true 


For the most accessible Umbraco Forms rendering, use Umbraco Forms v13.1.0 or newer, and don't forget to make the changes to appsettings.json! If upgrading isn't an option, there are some simple things that can be done to help with accessibility:

  • Upgrade to the most recent version of Umbraco Forms for your Umbraco install.
  • If the version of Umbraco Froms is earlier than Umbraco Forms v13.1.0 ask your content editors to add Captions for all the groups on all the forms.
  • Enable auto complete.
  • Review the form fields to ensure:
    • They have the data type set correctly.
    • There are no fields with hidden labels.

Of course, a custom theme may already have been implemented to resolve some of the issues listed in this article. In addition, if a custom theme has been implemented, if Umbraco Forms is upgraded as part of an Umbraco forms upgrade, the theme should also be reviewed to ensure compliance, as it will override any accessibility fixes implemented by Umbraco.

Remember, to create an accessible form, the form should be semantically correct, and the content author should also build it with a layout and copy that supports accessibility.