Component Accessibility Attributes
To make your components available to screen readers and other assistive technologies, use HTML attributes on your components. HTML attributes describe the UI elements that they contain. Accessibility software interprets UI elements by reading the attributes aloud.
One critical piece of accessibility is the use of the label attribute. By associating labels with a control, you allow assistive technology to present it to the user and let the user identify the purpose of the control. See WCAG label techniques.
Base Lightning components provide built-in accessibility. When you use a base component like lightning-input and lightning-record-form, the label you provide is automatically associated with the input field.
The input field is rendered with an associated label.
When the label element cannot be used, use the title attribute to identify form controls like buttons and input fields. See WCAG Technique H65. Screen readers read title attribute values to a user. When you use a Lightning web component with a title attribute, consider specifying a value. For example, the lightning-button component has a title attribute.
The title attribute doesn't display for keyboard users and can cause accessibility issues. If you're including important information for users and want your content to be accessible, we recommend making the text visible or using a base component like lightning-helptext.
That template creates HTML output like the following for the screen reader to read out “Log In” to the user.
The base component examples are for demonstration purposes only. Base component internals are subject to change. We document changes to the features and behavior of components, but don’t document changes to their internals. See the Component Reference for the public attributes and methods on a base component.
When you’re creating a Lightning web component, use @api to expose a public title attribute if you want a screen reader to read a value aloud to the user.
When you take control of an attribute by exposing it as a public property, the attribute no longer appears in the HTML output by default.
To pass the value through to the rendered HTML as an attribute (to reflect the property), define a getter and setter for the property and call the setAttribute() method.
You can also perform operations in the setter. Use a private property to hold the computed value.
For more information on using setAttribute(), see Reflect JavaScript Properties to HTML Attributes.
To provide more advanced accessibility, such as a screen reader reading out a button’s current state, use ARIA attributes. These attributes give more detailed information to the screen readers that support the ARIA standard.
You can associate ARIA attributes with id attributes in your HTML template. In a component’s template file, id values must be unique so that screen readers can associate ARIA attributes such as aria-describedby, aria-details, and aria-owns with specific elements.
When a template is rendered, id values may be transformed into globally unique values. Don’t use an id selector in CSS or JavaScript because it won’t match the transformed id. Instead, use the element's class attribute or a data-* attribute like data-id.
Let’s look at some code. The aria-pressed attribute tells screen readers to say when a button is pressed. When using a lightning-button component, you write:
The component defines the ARIA attributes as public properties, and uses fields to get and set the public properties.
The component JavaScript uses the camel-case attribute mappings to get and set the values in lightning-button.js.
The generated HTML is:
A screen reader that supports ARIA reads the label and indicates that the button is pressed.
ARIA attributes use camel-case in accessor functions. For example, aria-label becomes ariaLabel. The complete mapping list is defined in the LWC GitHub repo.
A component author may want to define default ARIA attributes on a custom component, and still allow component consumers to specify attribute values. In this case, a component author defines default ARIA values on the component’s element.
Define attributes in connectedCallback(). Don’t define attributes in constructor(). See Constructor Considerations.
When you use the component and supply an aria-label value, the supplied value appears.
The generated HTML is:
And, when you don’t supply an aria-label value, the default value appears.
The generated HTML is:
What if you create a custom component and don't want the value of an attribute to change? A good example is the role attribute. You don't want a component consumer to change button to tab. A button is a button.
You always want the generated HTML to have the role be button, like in this example.
To prevent a consumer from changing an attribute’s value, simply return a string. This example always returns "button" for the role value.
IDs and ARIA attributes in the same template are linked automatically. If attributes are in different templates, you must link them manually.
In native shadow DOM, you can’t link IDs and ARIA attributes between elements in separate templates.
To link together two elements using IDs and ARIA attributes, use light DOM to place them in the same shadow root. See the Accessibility section in Light DOM.