ToggleGroupControl: Fix accessible association of help text#76740
Merged
ToggleGroupControl: Fix accessible association of help text#76740
help text#76740Conversation
mirka
added
[Focus] Accessibility (a11y)
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
|
Size Change: -21 B (0%) Total Size: 7.73 MB
ℹ️ View Unchanged
|
|
Flaky tests detected in d36bc76. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/23802187611
|
ciampo
reviewed
Mar 26, 2026
Contributor
ciampo
left a comment
ciampo
left a comment
There was a problem hiding this comment.
Pre-approving since there's no blocking feedback. Feel free to merge once remaining feedback is addressed / responded to 🚀
Unrelated to this PR, but maybe we can add it regardless — while reviewing, I realised we don't set the id to the View when ToggleGroupControl is used as a button group.
The fix is simple:
diff --git i/packages/components/src/toggle-group-control/toggle-group-control/as-button-group.tsx w/packages/components/src/toggle-group-control/toggle-group-control/as-button-group.tsx
index 051bec811a0..a78aec7d5a8 100644
--- i/packages/components/src/toggle-group-control/toggle-group-control/as-button-group.tsx
+++ w/packages/components/src/toggle-group-control/toggle-group-control/as-button-group.tsx
@@ -83,6 +83,7 @@ function UnforwardedToggleGroupControlAsButtonGroup(
{ ...otherProps }
ref={ forwardedRef }
role="group"
+ id={ baseId }
>
{ children }
</View>
| className={ classes } | ||
| isAdaptiveWidth={ isAdaptiveWidth } | ||
| // `label` is used for `aria-label` on the inner control. | ||
| // This is separate from the visual label rendered by `BaseControl`. |
Contributor
There was a problem hiding this comment.
Again, not related to this PR, but noting that aria-label will take precedence over the <label>. It works fine, but maybe it's a symptom of the need for a better visual label or a future cleanup? or at least a lesson to learn for the @wordpress/ui work?
Member
Author
There was a problem hiding this comment.
Mm, right…. I would maybe say that this is a structural limitation of the BaseControl system, where it's not fully modular. Shouldn't be an issue with Field from Base UI, where we have easy modular access to the label element.
| return ( | ||
| <BaseControl help={ help }> | ||
| { ! hideLabelFromVision && ( | ||
| <VisualLabelWrapper> |
Contributor
There was a problem hiding this comment.
Can we remove VisualLabelWrapper without causing a regression (see original reson why it was added)
Member
Author
There was a problem hiding this comment.
Yes, confirmed horizontal alignment is correct.
| { value: 'right', label: 'Right' }, | ||
| { value: 'justify', label: 'Justify' }, | ||
| ].map( mapPropsToOptionComponent ), | ||
| help: 'Help text to describe the control.', |
Contributor
There was a problem hiding this comment.
Same comment as for ComboboxControl — should help text be featured in the default story, or moved to a dedicated story?
Member
Author
There was a problem hiding this comment.
Matched the pattern for newer component stories where we show help text by default. (No strong opinion though, hard to say which is "better".)
# Conflicts: # packages/components/CHANGELOG.md
Member
Author
Good catch, fixed in a56651c |
ObliviousHarmony
pushed a commit
that referenced
this pull request
Apr 1, 2026
* ToggleGroupControl: Associate help text with the control accessibly * Add help text to stories * Add changelog * ToggleGroupControl: Set id on button group View Co-authored-by: mirka <0mirka00@git.wordpress.org> Co-authored-by: ciampo <mciampini@git.wordpress.org>
adamsilverstein
pushed a commit
that referenced
this pull request
Apr 7, 2026
* ToggleGroupControl: Associate help text with the control accessibly * Add help text to stories * Add changelog * ToggleGroupControl: Set id on button group View Co-authored-by: mirka <0mirka00@git.wordpress.org> Co-authored-by: ciampo <mciampini@git.wordpress.org>
This file contains hidden or 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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What?
Fix the
helpprop onToggleGroupControlso that it is programmatically associated with the control viaaria-describedby. Also refactor the component to useuseBaseControlPropsmore fully, delegating label and help rendering toBaseControl.Why?
The
helptext was being rendered visually but had no accessible association with the radiogroup (or button group, in theisDeselectablecase). Screen reader users would not hear the help text when interacting with the control.The component was also hand-rolling its
hideLabelFromVisionlogic and not using theidfromuseBaseControlProps, duplicating whatBaseControlalready provides.How?
useBaseControlPropswithid,help,label, andhideLabelFromVision, and spread the returned props ontoBaseControland the inner control.idand addsaria-describedbyto the radiogroup/button group.BaseControlnow handles label rendering (including thehideLabelFromVisioncase), removing the need for the manualVisualLabelWrapperandBaseControl.VisualLabelusage.VisualLabelWrapperstyled component (and thestyledimport from Emotion).Testing Instructions
Automated
New unit tests cover:
hideLabelFromVisionis truehelptext is associated with theradiogroupviaaria-describedbyhelptext is associated with thegroupviaaria-describedbywhenisDeselectableManual
ToggleGroupControlstory in Storybook.helpprop to some text.aria-describedbypointing to the help text element.Use of AI Tools
Cursor with Claude was used to author this PR.