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: packages/documentation-site/patternfly-docs/content/accessibility/helper-text/helper-text.md
+23-5Lines changed: 23 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -30,7 +30,9 @@ To implement an accessible PatternFly **helper text**:
30
30
```
31
31
- Structure the helper text as a `ul` element and each helper text item as a `li` element if there is more than one helper text item.
32
32
- Make the helper text component an `aria-live` region if the helper text item(s) have static text and styling, but will dynamically render.
33
-
- Ensure there is visually hidden text for assistive technologies such as screen readers that conveys the status type if the helper text item has static text and will always be rendered, but the styling will dynamically update.
33
+
- Ensure there is visually hidden text for assistive technologies such as screen readers that conveys the status type if:
34
+
- the helper text item has static text and will always be rendered, but the styling will dynamically update, or
35
+
- the helper text item text content itself doesn't convey a status type
34
36
- Avoid passing interactive content as helper text.
35
37
36
38
## Testing
@@ -48,7 +50,7 @@ At a minimum, a helper text should meet the following criteria:
48
50
<Checkbox id="helperText-a11y-checkbox-3" label="If the helper text item(s) are intended to have static text and styling, but be dynamically rendered, the helper text component is made into a live region." description={<span>The <code className="ws-code">aria-live</code> value should be "polite" when doing so. This will announce to users of assistive technologies when new helper text has rendered, keeping them informed of any remaining criteria or issues that need to be addressed.</span>} />
49
51
</ListItem>
50
52
<ListItem>
51
-
<Checkbox id="helperText-a11y-checkbox-4" label="If the helper text item(s) are intended to have static text and always be visible, but have dynamic styling, ensure there is visually hidden text within the helper text item that conveys its status type." description={<span>This is best achieved by using our <code className="ws-code">pf-v5-screen-reader</code> class.</span>} />
53
+
<Checkbox id="helperText-a11y-checkbox-4" label="If the helper text item(s) are intended to have static text and always be visible, but have dynamic styling, or the helper text item(s) content doesn't convey a status, ensure there is visually hidden text within the helper text item that conveys its status type." description={<span>This is best achieved by using our <code className="ws-code">pf-v6-screen-reader</code> class.</span>} />
52
54
</ListItem>
53
55
<ListItem>
54
56
<Checkbox id="helperText-a11y-checkbox-5" label="There is no interactive content in any helper text items." />
@@ -67,7 +69,7 @@ The following React props have been provided for more fine-tuned control over ac
67
69
|`isLiveRegion`|`HelperText`| Makes the helper text component a live region with a value of `"polite"`. **Required** when helper text item(s) are intended or expected to have static text, but dynamically render. |
68
70
|`component="li"`|`HelperTextItem`| Sets the wrapper element of the helper text item to a list item. **Required** when `HelperText` has `component="ul"` passed in. |
69
71
|`id`|`HelperTextItem`| Sets the `id` attribute of the helper text item, which should be passed to the main element's `aria-describedby` attribute. |
70
-
|`screenReaderText="[text that conveys status type]"`|`HelperTextItem`| Renders visually hidden text when the `isDynamic` prop is also passed in. Typically this should convey the status type of the helper text item, and will render immediately after the item text. |
72
+
|`screenReaderText="[text that conveys status type]"`|`HelperTextItem`| Renders visually hidden text when the `isDynamic` prop is also passed in. Typically this should convey the status type of the helper text item, and will render immediately after the item text. This can be prevented from rendering by passing an empty string `''` as a value. |
71
73
|`variant="[default, indeterminate, warning, error, or success]"`|`HelperTextItem`| Sets the text styling and icon. This prop should only be passed in when the helper text item should visually convey some sort of status. |
72
74
73
75
## HTML/CSS customization
@@ -82,5 +84,21 @@ The following HTML attributes and PatternFly classes can be used for more fine-t
82
84
|`role="list"`|`ul.pf-v6-c-helper-text`| Indicates that the helper text component is a list element. **Required**.<br/><br/>This role is redundant since `.pf-v6-c-helper-text` can be a `<ul>` element, but it is required for assistive technologies to announce the list properly. |
83
85
|`id`|`.pf-v6-c-helper-text__item`| Sets the `id` attribute of the helper text item, which should be passed to the main element's `aria-describedby` attribute if the `.pf-v6-c-helper-text` element is not given an `id` instead. |
84
86
|`aria-hidden="true"`|`.pf-v6-c-helper-text__item-icon > i`| Removes the helper text item icon from the accessibility tree, preventing assistive technologies from potentially announcing duplicate or unnecessary information without visually hiding it. **Required**. |
85
-
|`.pf-v5-screen-reader`|`.pf-v6-c-helper-text__item.pf-m-dynamic > span`| Renders visually hidden text that is accessible only to assistive technologies such as a screen reader. **Required** if the helper text item is intended or expected to contain static text and always be visible, but have dynamic styling. Typically this should convey the status type of the helper text item. |
86
-
87
+
|`.pf-v6-screen-reader`|`.pf-v6-c-helper-text__item.pf-m-dynamic > span`| Renders visually hidden text that is accessible only to assistive technologies such as a screen reader. This should be included if the helper text item is intended or expected to contain static text and always be visible, but have dynamic styling, or if the helper text item content doesn't convey a status. Typically this should convey the status type of the helper text item. |
88
+
89
+
## Additional considerations
90
+
91
+
Consumers must ensure they take any additional considerations when customizing helper text, using it in a way not described or recommended by PatternFly, or in various other specific use-cases not outlined elsewhere on this page.
92
+
93
+
### Visually hidden text
94
+
95
+
While we recommend including visually hidden text for helper text items, it's important to understand more about the when and why. Typically we recommend including visually hidden text within the helper text item for 2 scenarios:
96
+
97
+
- the helper text item content is static, but the styling and status will dynamically change
98
+
- the helper text item content does not clearly convey any type of status
99
+
100
+
For the first scenario, if helper text item content will always remain static, any visual styling changes themselves won't be conveyed to users. Including visually hidden text within the helper text item can help convey that change in status and styling when navigating to the helper text item, but also via `aria-live` announcements. Without this visually hidden text, the same text content would be announced without any change at best, or nothing would be announced at worst in the case of `aria-live`.
101
+
102
+
For the second scenario, it can be difficult for some users to understand the difference between messages of different status types depending on the wording. Including visually hidden text that helps convey that status can help differentiate between the two, or better understand whether a single helper text item is crucial to continuing through a workflow or not.
103
+
104
+
It is also worth noting that localization must also be considered when it comes to the visually hidden text. If you provide localization elsewhere in your codebase - especially the area where helper text is being used - you must provide localization for the visually hidden text of the helper text item.
0 commit comments