States and properties

States and properties are characteristics of user interface (UI) elements that help users understand and interact with them.

Meeting the Web Accessibility Standard

When an element’s states and properties reflect the element's visual presentation, this meets WCAG 2 Success Criterion 1.3.1 Info and Relationships (Level A).

When states and properties that can be changed by a user can also be changed programmatically using assistive technologies (AT), and when AT are notified of changes to an element’s states and properties, this meets WCAG 2 Success Criterion 4.1.2 Name, Role, Value (Level A).

On this page

What are states and properties?

States and properties are characteristics of user interface (UI) elements — for example, a text input in a form might have the property of being required, and a checkbox is typically in either the checked or unchecked state. An element’s states and properties are expressed in HTML markup as attributes on the element, and are often directly related to the element’s role.

By reading the HTML markup, browsers and other software, especially assistive technologies (AT), can identify and communicate an element’s states and properties to users. These characteristics, alongside the element’s role, provide users with more information about the element to help them understand and interact with it. Not every element has or needs states or properties, but interactive UI components usually do.

An element’s states and properties get associated with the element’s corresponding accessible object in the accessibility tree.

For more on semantics and how web pages are made accessible to AT users, see the following Knowledge Areas:

States versus properties

Properties typically represent information that’s essential to an element, but sometimes it’s just a specific attribute value associated with the element. Generally, an element’s properties do not change very often, if at all.

States, on the other hand, are properties whose values are open to change, in response to something that the user does or to some programmatic event.

How states and properties are defined

Native HTML states and properties

The HTML Living Standard defines the states and properties associated with each HTML element. Many element states and properties are expressed as attributes on an element. For instance, on an <input> element that acts as a checkbox, the checked attribute indicates the element’s current state, checked or unchecked.

For the states and properties associated with a specific HTML element, see that element’s entry in the HTML Living Standard.

See also the HTML Living Standard’s table of all HTML attributes.

ARIA states and properties

The Web Accessibility Initiative’s Accessible Rich Internet Applications (WAI-ARIA) specification also defines a collection of state and properties. In some cases, the states and properties of HTML elements are already mapped by the browser to corresponding ARIA states or properties when they’re exposed in the accessibility tree. For more, see Implicit ARIA semantics below.

All ARIA states and properties are expressed in HTML markup as attributes whose names start with “aria-” — for instance, aria-haspopup.

Note: Accessible Rich Internet Applications (WAI-ARIA), or just ARIA, is a W3C technology for programmatically adding semantic information about content — such as its name, role, state or other properties. ARIA is intended to be used when the host markup language — for example, HTML — does not include elements or attributes with the semantics needed to represent the content.

When ARIA is used correctly, it enables assistive technologies (AT), especially screen readers, to relay the necessary semantic information about the content to the user.

As a rule, do not use ARIA if a native HTML element or attribute with the needed semantics or features already exists.

For more information, see:

ARIA defines 4 categories of state and property attributes:

For a list of all the ARIA states and properties, see:

How states and properties are assigned

Native HTML states and attributes

In HTML, element states and properties are typically assigned through attributes on the element as defined in the HTML Living Standard.

Implicit ARIA semantics

Note: Most HTML elements have default semantics that map to the semantics defined in the ARIA specification. These are an element’s “implicit WAI-ARIA semantics”.

For instance, when a browser comes across an <h1>, it exposes the element in the accessibility tree with a role of heading, as that’s the default ARIA role for each of the <h1>–<h6> elements. And as the heading role requires an aria-level property for the heading element’s level in the heading hierarchy, browsers use the number in the heading element's tag name to set the aria-level property which also gets exposed in the accessibility tree.

Some HTML attributes map directly to ARIA states or properties. For example, when it comes across the placeholder attribute on a <textarea>, a browser will expose that attribute in the accessibility tree as if it were the aria-placeholder property.

For more information, see Implicit WAI-ARIA Semantics — Accessible Rich Internet Applications (WAI-ARIA) — W3C.

While many HTML elements have implicit ARIA role semantics, some HTML attributes have implicit ARIA state or property semantics. For example, when it comes across the placeholder attribute on a <textarea>, a browser will expose that attribute in the accessibility tree as if it were the aria-placeholder property. A screen reader will read the placeholder’s value along with the <textarea>’s label and role when it identifies the element to the user.

Most HTML attributes do not have corresponding ARIA states or properties. But they might still be exposed through other mechanisms in the accessibility API. For example, the HTML datetime attribute on the <time> element does not map to any ARIA property, but the browser still exposes it as a property of the <time> element’s accessible object in the accessibility tree.

Some HTML attributes are not exposed through accessibility APIs at all because they provide no meaningful information to the user.

For a list of HTML element and attribute features with corresponding ARIA state and property semantics, see Requirements for use of ARIA attributes in place of equivalent HTML attributes — ARIA in HTML — W3C.

For a list of HTML attributes showing how they’re exposed through accessibility APIs and any default ARIA state or property mappings they have, see HTML Attribute State and Property Mappings — HTML Accessibility API Mappings (HTML-AAM) —W3C.

Explicitly declared ARIA states and properties

Authors can use ‘aria-’ attributes to assign HTML elements specific states and properties that are different from their default states and properties, including states and properties that do not have an equivalent in HTML.

Example of assigning ARIA states and properties

In the following markup, the aria-expanded attribute is assigned to a <button> to indicate that it controls an expandable container of content, and that the container is currently not expanded. The aria-controls attribute identifies the expandable container that the button controls.

<button aria-expanded=“false”
aria-controls=“details”>View details</button>

<div id=“details” hidden>These are the
details…</div>

Based on this markup, the browser exposes the <button> in the accessibility tree such that screen readers will announce something like, “View details, button, collapsed”.

When the <button> is activated, JavaScript removes the hidden attribute from the associated container, thereby making its content available visually and programmatically.

At the same time, the aria-expanded attribute’s value is changed to “true” to reflect the container’s current state. Ideally, a screen reader announces the change in state by saying something like, “Expanded”.

Note: Assigning ARIA states and properties to an element only changes how the element is exposed in the accessibility tree for AT users. It does not change the element’s functionality or how it is visually displayed.

If an element’s states or properties are associated with specific functionality or keyboard interaction, these need to be added, typically using JavaScript. For example, event handlers need to be scripted to update the aria-expanded attribute’s value so that it reflects that actual state of an associated expandable container.

For a list of HTML elements and the ARIA state and property attributes that can be explicitly assigned to them, see Document conformance requirements for use of ARIA attributes in HTML — ARIA in HTML — W3C.

When to assign states and properties

Native HTML

In native HTML, states and properties are assigned to elements by adding HTML attributes to the element, such as the checked attribute on an <input type="checkbox">.

Depending on the element, some HTML state and property attributes will be required, and some optional. To find out which HTML state and property attributes each HTML element requires or supports, see the element’s entry in the HTML Living Standard.

ARIA

Required states and properties

When using ARIA to create a custom user interface component or functionality, certain roles have required ARIA state or property attributes. For example, if a <div> element is given a role of checkbox, the required aria-checked attribute must be assigned to indicate the element’s current state. For a definition, see the ARIA specification’s section on Required States and Properties.

For each ARIA role’s required states and properties, if any, see the role’s entry in the ARIA specification.

Supported states and properties

Certain ARIA roles support, but do not require, certain states and properties that are specifically relevant to the role. For a definition, see the ARIA specification’s section on Supported States and Properties.

For instance, the button role does not require an aria-expanded state, but it supports its use when needed. If an element with a button role is used to expand and collapse some associated content, it should have an aria-expanded attribute to programmatically indicate the element’s purpose and current state to AT through the accessibility API.

Supported states or properties are only permitted with certain roles. For example, the aria-expanded state is only relevant to roles representing focusable, interactive controls that show and hide other content. As such, while it’s not explicitly prohibited, it’s not supported by every role, as most roles do not represent the relevant functionality.

In many cases, a role’s supported states or properties have default values that do not need to be explicitly assigned. In HTML, an element’s implicit ARIA semantics typically include any supported ARIA states and properties and their default values. Unless they are changed by the author, these supported states and properties are exposed in the accessibility tree with their default values.

For each ARIA role’s supported states and properties, see the role’s entry in the ARIA specification.

Global states and properties

ARIA defines a set of states and properties that are applicable to all roles, unless explicitly prohibited for a specific role. These states and properties can be applied to almost every HTML element.

For a list of these states and properties, see the ARIA specification’s section on Global States and Properties.

Inherited states and properties

Roles inherit certain states and properties by virtue of their position in the ARIA specification’s ontology of roles. In this ontology, each role that an author can use is part of a superclass role from which it inherits states and properties supported by that superclass role. For a definition, see the ARIA specification’s section on Inherited States and Properties.

A role’s inherited states and properties include all of the global states and properties, unless explicitly prohibited for the role in question.

For each ARIA role’s inherited states and properties, see the role’s entry in the ARIA specification.

Prohibited states and properties

Some ARIA roles have states and properties that are fully prohibited. In all but one case, these are the aria-label and aria-labelledby properties, and they’re prohibited because the role does not allow an accessible name to be provided by the page author. For more, see Elements that cannot be named using aria-label or aria-labelledby.

The generic role in particular is prohibited from having the aria-label and aria-labelledby properties, but also the aria-brailledescription and aria-roledescription properties.

For each ARIA role’s prohibited states and properties, if any, see the role’s entry in the ARIA specification.

Mixing ARIA states and properties with HTML elements

HTML elements with implicit ARIA roles can also take any ARIA state and property attributes that are required or supported by the role, without needing to explicitly declare the ARIA role.

For example, if aria-level="3" is added to an <h2> element, which has an implicit role of heading, a browser will already expose the <h2> as a level 3 heading because the aria-level property is a required property for the heading role.

If adding the aria-expanded attribute to a <button> or an <input type="checkbox">, it is not required to explicitly assign those elements a role of button or checkbox. Those elements already map by default to the button and checkbox roles, respectively, and the aria-expanded attribute is supported on those roles.

Special states and properties

Properties for naming and describing

State for hiding content from AT

The aria-hidden state attribute is used to indicate if an element is exposed in the accessibility tree and so available to AT users or not. For more information, see:

Properties for live regions

ARIA live regions are special regions of a web page whose content is announced by screen readers when it’s updated or changes, either in response to a user interaction or some external event. The following global attributes apply to live regions:

Note: There are a number of roles that by default act as live regions and can be modified using live region attributes. For more, see Live Region Roles in the ARIA specification.

For more on live regions and their attributes, see ARIA live regions — MDN Web Docs.

Meeting the Web Accessibility Standard

When the appropriate ARIA live region attributes (or live region role) are used with a status message so that the status message can be programmatically determined and automatically presented to a user of assistive technologies, without the status message needing to receive focus, this meets WCAG 2 Success Criterion 4.1.3 Status Messages (Level A).

Autocomplete property for identifying input purpose

The autocomplete property attribute lets us programmatically identify the specific type of personal information that an input field in a form is asking for about the person currently filling out that form. This information can then be used by software to indicate the type of information being requested in a way that best helps the user.

The specific types of personal information that can be identified using the autocomplete attribute are listed in WCAG 2’s Input Purposes for User Interface Components. If an input field is collecting — about the form’s current user — a type of information that has a corresponding input purpose in that list, then use that input purpose as the value for the <input> element’s autocomplete attribute.

For more information:

Meeting the Web Accessibility Standard

When an <input> element in a form is asking the current user for a type of personal information that has a corresponding input purpose listed in WCAG 2’s Input Purposes for User Interface Components, using that input purpose as the value for the <input> element’s autocomplete attribute meets WCAG 2 Success Criterion 1.3.5 Identify Input Purpose (Level AA).

Testing for states and properties

Use your web browser’s developer tools to inspect the accessibility information for the page you are viewing. For instructions, see Inspecting the accessibility tree — Knowledge Area: Browsers, code and assistive technologies.

  1. For any native HTML element whose implicit ARIA semantics are not overridden or modified by the explicit declaration of an ARIA role, state or property, check that:

    • it has all HTML state and property attributes that are required for the element — if in doubt, check the element’s entry in the HTML Living Standard

    • all of its other HTML state and property attributes are permitted on the element as defined in the HTML Living Standard.

  2. For any element whose implicit ARIA semantics are overridden or modified by the explicit declaration of an ARIA role, state or property, check that:

    • all states and properties that are required for the element and its role are provided, either inherently as part of the HTML element itself, or as HTML or ARIA state and property attributes — if in doubt, check the element’s entry in the HTML Living Standard and its role’s definition in the ARIA specification

    • all of its other HTML state and property attributes are permitted on the element as defined in the HTML Living Standard

    • all of its other ARIA state and property attributes are permitted with the element’s role as defined in the ARIA specification.