Button

Buttons communicate possible user actions. Clicking on a button allows a user to perform the corresponding action. Buttons appear differently based on their use category and the priority level of their call to action.

WCAG Score - Not compliant

Provided by the component

This component provides the following foundation for accessibility compliance:

Keyboard Navigation

Buttons are reachable via the Tab key in a logical order.

Buttons can be activated using Space, following native browser behavior.

Focus states are visually indicated to help keyboard users track their current position on the page.

Visual & Color Accessibility

Default button styles provide sufficient contrast between text/icon and background, meeting WCAG contrast guidelines.

Focus, hover, and active states are visually distinct to support different user needs (keyboard, mouse, touch).

Resizing / Target Size

Hit-area and spacing meet minimum target size recommendations for touch and pointer accessibility.

It is designed to meet WCAG 2.5.8 – Target Size (Minimum): interactive elements should have a minimum target size of 24 × 24 CSS pixels.

Implementation considerations

Developers must do the following in the implementation to be considered fully accessible:

Loading Button

Set the translations.ariaLabelLoadingMessage prop from object to give screen-reader users to say while the button is loading. The default string is “Loading”; swap it for any language-specific or task-specific message to keep in the same language the rest of the app uses.

While the button is loading, it signals to assistive technologies that the control is in a loading state via aria-busy="true". Additionally, we use aria-disabled to announce that the button is not available at this time.

Additionally, we expose aria-controls where the user can tell screen readers that “this button can change something over there” where the value is the IDof the element that gets changed.

For example:


                                                        
                                                        
                                                            <WButton aria-controls="changed-area-box" label="Search" />
                                                        <div id="changed-area-box"> … </div>

Extended Labels

When the visible button label needs additional context for screen readers, you can pass aria-label as a standard HTML attribute:
<w-button label="Export" aria-label="Export data to CSV" />

Important: The aria-label must include the visible label text (ideally at the beginning) to comply with WCAG 2.5.3 - Label in Name.

✅ Good: label="Export" aria-label="Export data to CSV"

Don't

❌ Bad: label="Export" aria-label="Download file"

Buttons vs links

The types of actions performed by buttons are distinctly different from the function of a link (generally links go somewhere and buttons do something). It is important that both the appearance and role of a button, match the function it provides.

That’s why we aim for a differentiated visual design that streamlines the component's function and its ARIA role. We are aware of the exception we are introducing with the plain button variant. Check the best practices above for more details on how to use them.