Skip to content

Commit

Permalink
docs: add accessibility docs to Switch component
Browse files Browse the repository at this point in the history
  • Loading branch information
domihustinova committed Jan 28, 2025
1 parent 0328f02 commit 08d9739
Showing 1 changed file with 53 additions and 0 deletions.
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
---
title: Accessibility
redirect_from:
- /components/switch/accessibility/
---

## Accessibility

The Switch component has been designed with accessibility in mind.

It supports keyboard navigation and includes the following properties that provide additional information to screen readers:

| Name | Type | Description |
| :------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ariaControls | `string` | Allows you to specify an `aria-controls` attribute to establish the relationship between the Switch and element which is controlled by it. `ariaControls` works only with a unique `id` of an element. |
| ariaLabel | `string` | Allows you to specify an `aria-label` attribute of the component. |
| ariaLabelledby | `string` | Allows you to specify an `aria-labelledby` attribute of the component. This attribute references the id(s) of element(s) that label(s) the Switch, separated by a space. The elements with those ids can be hidden, so that their text is only announced by screen readers. |

While these props are optional, we recommend including them to ensure proper functionality with assistive technologies.
This helps users better understand the component's context and improves the overall experience.

### Example

The following code snippet shows how to use these properties:

```jsx
<Card
title="Billing details"
actions={
<Switch
checked={isExpanded}
onChange={handleShowBillingDetails}
ariaLabel="Toggle billing details section"
ariaControls="BillingDetailsForm"
/>
}
>
{isExpanded && (
<CardSection>
<BillingDetailsForm id="BillingDetailsForm" />
</CardSection>
)}
</Card>
```

Using the `ariaLabel` prop enables screen readers to properly announce the Switch component.
Alternatively, you can use the `ariaLabelledby` prop to reference another element that serves as a label for the Switch component.

For enhanced accessibility, it is recommended to have these label strings translated and dynamically updated based on the user's current journey state
(e.g. if a billing details section is expanded and the user is about to collapse it, the screen reader should properly announce it).

The `ariaControls` prop establishes a connection between the Switch and the element it controls.
This relationship enables users to navigate directly from the Switch to this element, improving the overall navigation experience.

0 comments on commit 08d9739

Please sign in to comment.