fix: expose input styling on RAC Checkbox and Radio

[gonzoblasco]

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]

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]

@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.

[snowystinger]

VisuallyHidden has highly specific styles right now that ensure it's visible to screen readers. If we expose all of these styles, it'd be pretty easy for people to accidentally make it not accessible.

For example, making it full width and height would probably show the native browser chrome for the input. The natural thing to do is then to use visibility hidden. This is not accessible.

Please include a story that you, the person, confirm this works on. Including screen readers. Once we have that maybe we can find some smaller API to expose, as we do not want to expose all of these props if possible.

[gonzoblasco]

You're right that exposing raw control over VisuallyHidden gives people a lot of rope, and the visibility: hidden trap is a real one - it is the natural thing to reach for and it does break screen reader exposure.

Two things I'd like to do:

1. Add a story and validate it with a real screen reader. I'll add a story for Checkbox and Radio that stretches the hidden input over the component using the documented technique (visuallyHiddenStyle={{inset: 0, width: 'auto', height: 'auto'}} + inputStyle={{position: 'absolute', inset: 0}}), and confirm with VoiceOver that the focus ring tracks the component and the input stays exposed.

2. Propose a smaller API. Instead of exposing all four props (inputClassName/inputStyle + visuallyHiddenClassName/visuallyHiddenStyle), I'd rather explore a single prop that encodes the safe pattern and keeps VisuallyHidden encapsulated. Something like a focusRing or inputPosition boolean that applies the correct positioning internally (label as containing block, wrapper stretched, input filling it) without handing out arbitrary style/className access. That achieves the fix for the reported issue with a much smaller surface, and it cannot be used to accidentally un-accessible the component.

My instinct is option 2 is the right shape for a library like this - the reported issue is specifically about the screen reader focus ring not tracking the component, and a boolean that encodes "make the hidden input cover the component" solves exactly that without exposing implementation details.

Want me to put together a proposal for the smaller prop (with the story + VoiceOver check) so we can compare it side by side against the current approach?

[snowystinger]

yes, let's explore a smaller api

[gonzoblasco]

Validated the story I added (CheckboxScreenReaderFocusRing and RadioGroupScreenReaderFocusRing) on Chrome desktop with VoiceOver - the focus indicator tracks the checkbox and its label, which is exactly the reported issue.

Validating visually also surfaced a deeper preexisting bug in RAC Checkbox and RadioGroup that the current fix does not solve, and I want to flag it before we go further with the current approach.

Observation: in Chrome desktop (with system theme), the native browser chrome for the checkbox/radio input is rendered on top of the custom SVG mark when the component is checked. This is visible on:

• CheckboxExample (no fix, original story) - the native check square shows inside the SVG box.
• RadioGroupExample and RadioGroupControlledExample (no fix) - the native radio dot shows inside the SVG ring.
• CheckboxScreenReaderFocusRing and RadioGroupScreenReaderFocusRing (with the fix applied) - the native chrome becomes more prominent because the stretched input is now positioned over the custom SVG.

So the current fix exposes four style props that solve the bounding box issue (the input now covers the visible component) but does not solve the native chrome overlay. In fact, by stretching the input over the visible component, the native chrome overlay is now bigger and more obvious.

Root cause: the hidden input has appearance: auto (the default), so the browser renders the native widget on top of any CSS clip the VisuallyHidden wrapper applies. The VisuallyHidden wrapper clips the bounding box, but the native widget render does not respect CSS clip in modern Chrome/Firefox/Safari. The fix would need to set appearance: none on the input for the chrome to actually be hidden, but that is not something a consumer should have to know to add manually.

This means the smaller API you suggested is not just a nice-to-have - it is necessary to solve the actual bug. A single boolean prop that internally does the positioning correctly AND applies appearance: none to the input would solve both the SR focus ring and the native chrome overlay in one place, and it cannot be used to accidentally regress the appearance of the component.

Two questions before I rework the PR:

1. Does the boolean prop direction sound right, or would you prefer something different (a separate inputClassName only, or keeping the four props and documenting the appearance: none requirement)?
2. Should the boolean default to true (fix the chrome overlay for everyone, since it is currently a bug) or false (opt-in, to avoid any visual change for existing users)?

Want me to put together the smaller prop proposal once we agree on the direction?

[snowystinger]

I'm not sure what the prop should look like, a boolean probably isn't enough. If you refer back to the conversation on the Issue, one of the worries was that there were multiple ways that someone could want to style everything. However, I think it might be better to name those scenarios and add them as we come across them.

For instance, you're currently demoing the "full height and width in a relative element" (open to naming ideas). Since you're using AI, you might ask it to think of other scenarios.

The other thing we could do is, if position relative is the resolved style on the checkbox (check in a useLayoutEffect), then we could apply the full height/width automatically. I'm not sure if that'll break anything. It'd be susceptible to being changed outside of React's lifecycle as well. But maybe there are other ideas to explore around this.

[gonzoblasco]

Good points. A boolean definitely isn't enough. I think the explicit style props we have now are the right escape hatch for arbitrary scenarios, but a named prop for the common case would be much cleaner.

The scenario I'm demoing is essentially "stretch the hidden input to the visual label". We could expose that as hiddenInput="stretch-to-label" (or inputLayout="stretch-to-label", naming TBD). It would apply the absolute-inset styles to the VisuallyHidden wrapper and the native input internally. The consumer would still need to make the label a positioned containing block (position: relative), and we'd document that requirement. We could add a dev-only warning if the prop is used but the label isn't positioned.

Other scenarios I can think of:

• Stretch to button for CheckboxButton/RadioButton - the containing block is already the button itself, so this could apply without extra consumer setup.
• Custom hit area - e.g. a checkbox inside a clickable card where the hidden input needs to cover the whole card. That's best handled by the explicit style props, since the coordinates depend on the consumer's layout.
• Match the visible focus ring - we can't control the SR's ring color/thickness, but we can at least align its bounding box with the visible ring via the explicit style props.

On auto-detecting position: relative with useLayoutEffect: I'd lean against it. The resolved style may not be available at first paint if it comes from async CSS-in-JS injection, the containing block might be an ancestor rather than the checkbox itself, and silently mutating the hidden input's style outside React feels fragile with SSR. An explicit prop seems more predictable.

If you want, I can update the PR with hiddenInput="stretch-to-label" and keep the explicit style props as the advanced escape hatch. What do you think of the naming and direction?