ARIA: form role

A form landmark identifies a region of content that contains a collection of items and objects that, as a whole, combine to create a form when no other named landmark is appropriate (e.g. main or search).

Use the HTML <form> element if possible. The <form> element defines a form landmark when it has an accessible name (e.g. aria-labelledby, aria-label or title). Make sure to have a unique label on each form in a document to help users understand the purpose of the form. This label should be visible to all users, not just assistive technology users. Use the search landmark instead of the form landmark when the form is used for search functionality.

Use the role="form" to identify a region of the page; do not use it to identify every form field. Even if you are using the form landmark instead of <form>, you are encouraged to use native HTML form controls like <button>, <input>, <select>, and <textarea>.

No role specific states or properties.

No role specific keyboard interactions

onsubmit

The onSubmit event handler handles the event raised when the form is submitted. Anything that is not a <form> cannot be submitted, therefore you would have to use JavaScript to build an alternative data submission mechanism, for example with fetch().

<div role="form" id="send-comment" aria-label="Add a comment">
  <label for="username">Username</label>
  <input
    id="username"
    name="username"
    autocomplete="nickname"
    autocorrect="off"
    type="text" />

  <label for="email">Email</label>
  <input
    id="email"
    name="email"
    autocomplete="email"
    autocapitalize="off"
    autocorrect="off"
    spellcheck="false"
    type="text" />

  <label for="comment">Comment</label>
  <textarea id="comment" name="comment"></textarea>

  <input value="Comment" type="submit" />
</div>

It is recommended to use <form> instead.

<form id="send-comment" aria-label="Add a comment">…</form>

Landmark roles are intended to identify larger overall sections of the document. Using too many landmark roles can create "noise" in screen readers, making it difficult to understand the overall layout of the page.

You do not need to declare role="form" on every form element (inputs, text areas, selects, etc.). It should be declared on the HTML element that wraps the form elements. Ideally, use the <form> element as the wrapping element and do not declare role="form".

If a form is used to search, you should use the more specialized role="search" value.

Each <form> element and form role that needs to be exposed as a landmark must be given an accessible name. This name will allow an assistive technology user to be able to quickly understand the purpose of the form landmark.

Use an aria-labelledby, aria-label or title on the same element that was given the role="form" to provide it an accessible name.

Using role="form"

<div role="form" id="gift-cards" aria-label="Purchase a gift card">
  <!-- form content -->
</div>

Redundant descriptions

Screen readers will announce the type of role the landmark is. Because of this, you do not need to describe what the landmark is in its label. For example, a declaration of role="form" with an of aria-label="Contact form" may be announced redundantly as, "contact form form".

Using the <form> element will automatically communicate a section has a role of form. If at all possible, prefer using it instead.

• The <form> element
• The <legend> element
• form (role): Accessible Rich Internet Applications (WAI-ARIA) 1.1