Skip to content

fix: expose input styling on RAC Checkbox and Radio - #10517

Open
gonzoblasco wants to merge 1 commit into
adobe:mainfrom
gonzoblasco:fix/checkbox-radio-sr-focus-indicator
Open

fix: expose input styling on RAC Checkbox and Radio#10517
gonzoblasco wants to merge 1 commit into
adobe:mainfrom
gonzoblasco:fix/checkbox-radio-sr-focus-indicator

Conversation

@gonzoblasco

@gonzoblasco gonzoblasco commented Aug 27, 2026

Copy link
Copy Markdown

Why

Screen readers (VoiceOver, NVDA) draw their focus indicator around the native
<input> element, not around the visible component. In Checkbox and Radio the
input is rendered inside VisuallyHidden, which collapses it to 1x1px
(width: 1px; height: 1px; position: absolute; clip: rect(0 0 0 0)). The result
is that the screen reader focus ring shows up as a tiny square in the corner of
the component, disconnected from the visual focus. That is confusing for users
with low vision who rely on both the visual focus cue and the assistive
technology outline.

What changed

Expose inputClassName/inputStyle and visuallyHiddenClassName/visuallyHiddenStyle
on Checkbox, CheckboxField, Radio, RadioField, CheckboxButton, and RadioButton so
users can size and position both the hidden input and its VisuallyHidden wrapper
to encompass the visible component, making the screen reader focus ring match the
visual one.

The props follow the existing inputRef pattern already on these components and
are optional, so there is no behavior change by default.

Usage

To make the screen reader focus ring match the component, the label must be a
positioned containing block (position: relative), the VisuallyHidden wrapper
must be stretched to the label, and the input must fill the wrapper:

<Checkbox
  style={{position: 'relative'}}
  visuallyHiddenStyle={{inset: 0, width: 'auto', height: 'auto'}}
  inputStyle={{position: 'absolute', inset: 0, width: '100%', height: '100%'}}>
  Accept
</Checkbox>

The position: relative on the label is required because the input is
absolutely positioned; without a positioned ancestor it would resolve against
the viewport instead of the component. This is documented on the new props.

Testing

  • Added real-browser layout tests (not jsdom) that measure the hidden input's
    bounding box against the component, verifying the input covers the component
    rather than the viewport. This addresses the review feedback that jsdom cannot
    validate layout.
  • All 128 tests in the Checkbox and RadioGroup suites pass, check-types and
    lint are clean.

Fixes #9687

Findings

While implementing this fix I found a couple of related cases that are out of scope for this PR but worth flagging:

  • Switch uses the same pattern as Checkbox and Radio: its native input is rendered inside VisuallyHidden and collapsed to 1x1px, so it likely has the same screen reader focus indicator issue. It does not have inputClassName/inputStyle either. Since [Bug]: Screen reader focus indicator is misaligned for Checkbox and Radio components [react-aria-components] #9687 only mentions Checkbox and Radio, I did not expand the scope here, but Switch is a good candidate for a follow-up.
  • Slider, Table, and HiddenDateInput also render a native input inside VisuallyHidden. These are different cases (range input, selection, and date input respectively), but if the same fix is wanted across the library, the inputClassName/inputStyle pattern could be extended consistently.

Happy to follow up on Switch if the maintainers want it. Otherwise these are documented for future work.

@snowystinger snowystinger left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the PR. I don't think this is going to work. VisuallyHidden wraps the input in a position absolute. So anything inside it will be positioned relative to it. In addition, it has height and width of 1, so anything inside it using height/width 100% would still only be 1px.
I'd start by proving that it works in the browser using storybook, not unit tests, jsdom is a pretty bad place to test that this works.

@gonzoblasco

Copy link
Copy Markdown
Author

@snowystinger you are right, and I verified it in a real browser. Thanks for the push to test this properly instead of relying on jsdom.

I reproduced the exact VisuallyHidden styles (position absolute, 1x1px, clip rect(0 0 0 0), clip-path inset(50%)) in a Chromium page and measured the real bounding boxes of the hidden input vs the visible component. The results:

  • inputStyle={{inset: 0}} (as proposed): the input is position: static, so inset is ignored and it keeps its natural size (~153x21), which does not match the component.
  • inputStyle={{inset: 0, position: 'absolute'}}: the input is now positioned relative to the 1x1px wrapper, so inset: 0 collapses it to roughly 1x1px. Same with width/height: 100% - it resolves against the 1x1px wrapper, not the component.
  • position: fixed + inset: 0: covers the whole viewport, not the component, and would break the click target.

So exposing inputStyle/inputClassName cannot make the screen reader focus ring match the visual one. The VisuallyHidden wrapper imposes the 1x1px absolute box plus the clip, and the input cannot escape that with reasonable inline styles. The jsdom tests only assert the attribute is present, not that the layout works - exactly the gap you flagged.

I'll rework this PR with a different approach. The real fix likely needs to change how the hidden input is laid out for these components (or how the screen reader focus ring is drawn), rather than exposing styles on the input. I'll dig into #9687 and come back with something that actually works in the browser.

Screen readers (VoiceOver, NVDA) draw their focus indicator around the
native input element, not the visible component. In Checkbox and Radio
the input is rendered inside VisuallyHidden, which collapses it to 1x1px,
so the screen reader focus ring shows up as a tiny square disconnected
from the visual focus.

Expose inputClassName/inputStyle and visuallyHiddenClassName/visuallyHiddenStyle
on Checkbox, CheckboxField, Radio, RadioField, CheckboxButton, and RadioButton
so users can size and position both the hidden input and its VisuallyHidden
wrapper to encompass the visible component. The props follow the existing
inputRef pattern and are optional, so there is no behavior change by default.

To make the screen reader focus ring match the component, the label must be
a positioned containing block (position: relative), the VisuallyHidden wrapper
must be stretched to the label (e.g. {inset: 0, width: 'auto', height: 'auto'}),
and the input must fill the wrapper ({position: 'absolute', inset: 0, width: '100%', height: '100%'}).
This is documented on the new props.

Adds real-browser layout tests (not jsdom) that measure the hidden input's
bounding box against the component, verifying the input covers the component
rather than the viewport. This addresses the review feedback that jsdom
cannot validate layout.

Fixes adobe#9687
@gonzoblasco
gonzoblasco force-pushed the fix/checkbox-radio-sr-focus-indicator branch from 1de6149 to 393b02c Compare August 27, 2026 12:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug]: Screen reader focus indicator is misaligned for Checkbox and Radio components [react-aria-components]

2 participants