You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/src/documentation/03-components/05-input/inputfield/03-accessibility.mdx
+78-19
Original file line number
Diff line number
Diff line change
@@ -4,28 +4,87 @@ redirect_from:
4
4
- /components/inputfield/accessibility/
5
5
---
6
6
7
-
###Accessibility
7
+
## Accessibility
8
8
9
-
- For special cases you can use your own, detached `label`. Simply like this:
9
+
The InputField component has been designed with accessibility in mind, providing features that enhance the experience for users of assistive technologies.
10
+
11
+
### Accessibility props
12
+
13
+
The following props are available to improve the accessibility of your InputField component:
| label |`Translation`| Provides a visible label that is associated with the input field. |
18
+
| role |`string`| Defines the role of the input element, which helps screen readers understand its purpose and behavior. |
19
+
| ariaLabel |`string`| Adds an `aria-label` to the input, providing a description for screen readers when no visible label is present. |
20
+
| ariaLabelledby |`string`| References the ID of an element that labels the input, establishing a relationship for screen readers. |
21
+
| ariaDescribedby |`string`| References the ID of an element that describes the input, useful for associating additional information with the field. |
22
+
| ariaAutocomplete |`inline \| list \| both \| none`| Indicates to screen readers whether and how the input provides autocomplete suggestions. |
23
+
| ariaActiveDescendant |`string`| Identifies the currently active descendant in a composite widget, such as when navigating through autocomplete suggestions. |
24
+
| ariaHasPopup |`boolean`| Indicates to screen readers that the input can trigger a popup, like a dropdown menu or dialog. |
25
+
| ariaExpanded |`boolean`| Indicates to screen readers whether the associated popup or dropdown is currently expanded. |
26
+
| ariaControls |`string`| Identifies the element controlled by the input, establishing a relationship for screen readers. |
27
+
28
+
### Automatic Accessibility Features
29
+
30
+
The InputField component automatically handles several important ARIA attributes:
31
+
32
+
-`aria-invalid`: When the `error` prop is provided, the input is automatically marked as invalid (`aria-invalid="true"`). This helps screen readers announce to users that the input contains an error.
33
+
34
+
-`aria-describedby`: This attribute is automatically managed to associate `error` or `help` text with the input field:
35
+
- When the component is not inside an InputGroup and has `error` or `help` text, a unique ID is generated (based on the input's ID) and is combined with the `ariaDescribedby` prop to ensure all descriptions are announced by screen readers.
36
+
- When the component is inside an InputGroup, the InputGroup completely overrides any `ariaDescribedby` value that was set on the InputField. The InputGroup sets its own feedback ID as the `aria-describedby` value if there are any `error` or `help` values and the tooltip is shown.
37
+
38
+
These automatic features ensure that the InputField remains accessible even without explicitly setting every ARIA attribute, while still allowing for customization when needed. See the [Examples section](#using-ariadescribedby-for-enhanced-accessibility) for detailed usage examples of `ariaDescribedby`.
39
+
40
+
### Best practices
41
+
42
+
- When no visible `label` is provided, use `ariaLabel` to provide an accessible name for the input field to ensure the input's purpose is clear to screen reader users. Alternatively, you can use `ariaLabelledby` to reference the ID of an existing element that labels the input.
43
+
44
+
- Always ensure that `ariaLabel` text and any text in elements referenced by `ariaLabelledby` are properly translated to match the user's language.
45
+
46
+
- Don't rely solely on `placeholder` for providing instructions or label of the input.
47
+
48
+
- For inputs that trigger autocomplete behavior or control other elements, use the appropriate ARIA attributes (`ariaAutocomplete`, `ariaActiveDescendant`, `ariaHasPopup`, `ariaExpanded`, `ariaControls`) to make the functionality accessible.
49
+
50
+
- When using `prefix` or `suffix` elements, ensure they don't interfere with the accessibility of the input field and are properly labeled if they are interactive.
In this example, screen readers would announce "Email address, required, edit, email" when focusing on the input field.
61
+
62
+
#### InputField with autocomplete
10
63
11
64
```jsx
12
-
<label for="NICEID">Content</label>
13
65
<InputField
14
-
id="NICEID"
66
+
label="City"
67
+
placeholder="Start typing..."
68
+
role="combobox"
69
+
ariaHasPopup={true}
70
+
ariaExpanded={suggestionsVisible}
71
+
ariaControls="city-suggestions"
72
+
ariaAutocomplete="list"
73
+
ariaActiveDescendant={activeItemId}
15
74
/>
16
75
```
17
76
18
-
- The `ariaLabel` prop allows you to specify an `aria-label` attribute for the InputField component. This attribute provides additional information to screen readers, enhancing the accessibility of the component. By using `ariaLabel`, you can ensure that users who rely on assistive technologies receive the necessary context and information about the component's purpose and functionality.
77
+
In this example, the InputField is configured as a combobox with autocomplete features. Screen readers would announce information about the combobox state, including whether suggestions are available and which suggestion is currently active.
19
78
20
-
- If the `label` prop is not provided, the `ariaLabel` prop must be specified to ensure component accessibility.
79
+
#### Using ariaDescribedby for enhanced accessibility
21
80
22
-
-The `ariaDescribedby` prop allows you to specify an `aria-describedby` attribute for the InputField component. This attribute links the component to additional descriptive text, enhancing accessibility by providing supplementary information to screen readers.
81
+
The `ariaDescribedby` prop allows you to specify an `aria-describedby` attribute for the InputField component. This attribute links the component to additional descriptive text, enhancing accessibility by providing supplementary information to screen readers.
Password must be at least 8 characters long and include at least one uppercase letter and one number.
87
+
</p>
29
88
```
30
89
31
90
When using the `error` or `help` props, the component automatically manages the `aria-describedby` attribute:
@@ -39,10 +98,10 @@ In this example, the error message is automatically associated with the input fi
39
98
If you provide both an `ariaDescribedby` prop and use `error` or `help`, the component automatically combines them, ensuring that screen readers announce all descriptive content:
In this example, both the "email-hint" text and the error message will be announced by screen readers. The text from `ariaDescribedby` will be announced first, followed by the text from `error`.
@@ -51,9 +110,9 @@ In this example, both the "email-hint" text and the error message will be announ
51
110
52
111
When using InputField within an InputGroup, the `aria-describedby` association follows these rules:
53
112
54
-
#### Example 1
113
+
#### Group-level error/help messages
55
114
56
-
If the InputGroup has `error`/`help` messages, these will be properly associated with all child components:
115
+
If the InputGroup has `error`/`help` messages, all child components will have `aria-describedby` set to these values **by default:**
@@ -64,7 +123,7 @@ If the InputGroup has `error`/`help` messages, these will be properly associated
64
123
65
124
In this example, all InputField components will have the InputGroup's error message "Incomplete information" announced by screen readers.
66
125
67
-
#### Example 2
126
+
#### Component-level error/help messages
68
127
69
128
If individual InputField components have their own `error`/`help`messages (and the InputGroup doesn't), only those specific components will have `aria-describedby` set:
70
129
@@ -77,7 +136,7 @@ If individual InputField components have their own `error`/`help` messages (and
77
136
78
137
In this example, only the second InputField will have its error message "Last name is required" announced.
79
138
80
-
#### Example 3
139
+
#### Component-level ariaDescribedby value
81
140
82
141
Avoid setting `ariaDescribedby` directly on InputField components when inside an InputGroup, as these values will be overwritten by the InputGroup's internal accessibility logic:
0 commit comments