-
Notifications
You must be signed in to change notification settings - Fork 152
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add accessibility docs to Switch component
- Loading branch information
1 parent
0328f02
commit 08d9739
Showing
1 changed file
with
53 additions
and
0 deletions.
There are no files selected for viewing
53 changes: 53 additions & 0 deletions
53
docs/src/documentation/03-components/07-interaction/switch/03-accessibility.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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. |