Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(core): deterministic tab stop for unselected RadioList groups (#3390)

Cindy Zhang45c58e9ff5dd
diff --git a/.changeset/radiolist-focus-no-selection.md b/.changeset/radiolist-focus-no-selection.md
new file mode 100644
index 0000000000..a05bdd8242
--- /dev/null
+++ b/.changeset/radiolist-focus-no-selection.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] RadioList: give an unselected radio group a deterministic keyboard tab stop. When focus enters a group with no selected value, the group now normalizes the entry point — first radio when tabbing forward, last radio when tabbing backward — matching the ARIA radio-group pattern. A selected value keeps its native tab stop, and moving between radios inside the group is never redirected. (#3390)
+@cixzhang
diff --git a/packages/core/src/RadioList/RadioList.test.tsx b/packages/core/src/RadioList/RadioList.test.tsx
index 27409cfb3d..22c6e52e6a 100644
--- a/packages/core/src/RadioList/RadioList.test.tsx
+++ b/packages/core/src/RadioList/RadioList.test.tsx
@@ -104,11 +104,7 @@ describe('RadioList', () => {
const user = userEvent.setup();
const handleChange = vi.fn();
render(
- <RadioList
- label="Preference"
- value=""
- onChange={handleChange}
- isDisabled>
+ <RadioList label="Preference" value="" onChange={handleChange} isDisabled>
<RadioListItem label="Option A" value="a" />
</RadioList>,
);
@@ -257,11 +253,7 @@ describe('RadioList', () => {
it('supports data-testid on RadioListItem', () => {
render(
<RadioList label="Preference" value="" onChange={() => {}}>
- <RadioListItem
- label="Option A"
- value="a"
- data-testid="my-radio-item"
- />
+ <RadioListItem label="Option A" value="a" data-testid="my-radio-item" />
</RadioList>,
);
expect(screen.getByTestId('my-radio-item')).toBeInTheDocument();
@@ -340,4 +332,106 @@ describe('RadioList', () => {
'true',
);
});
+
+ describe('focus management (no-selection tab stop)', () => {
+ it('keeps focus on the selected radio when a value is selected', () => {
+ render(
+ <RadioList label="Preference" value="b" onChange={() => {}}>
+ <RadioListItem label="Option A" value="a" />
+ <RadioListItem label="Option B" value="b" />
+ <RadioListItem label="Option C" value="c" />
+ </RadioList>,
+ );
+ const selected = screen.getByLabelText('Option B');
+ // A selected value provides a deterministic native tab stop; focusing it
+ // must not be redirected elsewhere.
+ selected.focus();
+ expect(selected).toHaveFocus();
+ });
+
+ it('redirects to the first radio when focus enters an unselected group forward', () => {
+ render(
+ <>
+ <button type="button">before</button>
+ <RadioList label="Preference" value="" onChange={() => {}}>
+ <RadioListItem label="Option A" value="a" />
+ <RadioListItem label="Option B" value="b" />
+ <RadioListItem label="Option C" value="c" />
+ </RadioList>
+ </>,
+ );
+ const radios = screen.getAllByRole('radio');
+ const outside = screen.getByText('before');
+ outside.focus();
+ // Forward entry: the browser lands on a leading radio; the group keeps the
+ // first radio as the deterministic tab stop.
+ radios[0].focus();
+ expect(radios[0]).toHaveFocus();
+
+ // Landing on a middle radio from outside is normalized to the first.
+ outside.focus();
+ radios[1].focus();
+ expect(radios[0]).toHaveFocus();
+ });
+
+ it('redirects to the last radio when focus enters an unselected group backward', () => {
+ render(
+ <>
+ <RadioList label="Preference" value="" onChange={() => {}}>
+ <RadioListItem label="Option A" value="a" />
+ <RadioListItem label="Option B" value="b" />
+ <RadioListItem label="Option C" value="c" />
+ </RadioList>
+ <button type="button">after</button>
+ </>,
+ );
+ const radios = screen.getAllByRole('radio');
+ const outside = screen.getByText('after');
+ outside.focus();
+ // Backward (Shift+Tab) entry: the browser focuses the last radio; the
+ // group keeps it as the deterministic tab stop rather than jumping away.
+ radios[radios.length - 1].focus();
+ expect(radios[radios.length - 1]).toHaveFocus();
+ });
+
+ it('does not hijack focus moving between radios within the group', () => {
+ render(
+ <RadioList label="Preference" value="" onChange={() => {}}>
+ <RadioListItem label="Option A" value="a" />
+ <RadioListItem label="Option B" value="b" />
+ <RadioListItem label="Option C" value="c" />
+ </RadioList>,
+ );
+ const radios = screen.getAllByRole('radio');
+ // Enter the group from outside, then move to a middle radio as arrow-key
+ // navigation would. Intra-group movement must not be redirected back.
+ radios[0].focus();
+ radios[1].focus();
+ expect(radios[1]).toHaveFocus();
+ radios[2].focus();
+ expect(radios[2]).toHaveFocus();
+ });
+
+ it('skips disabled radios when choosing the deterministic tab stop', () => {
+ render(
+ <>
+ <button type="button">before</button>
+ <RadioList label="Preference" value="" onChange={() => {}}>
+ <RadioListItem label="Option A" value="a" isDisabled />
+ <RadioListItem label="Option B" value="b" />
+ <RadioListItem label="Option C" value="c" />
+ <RadioListItem label="Option D" value="d" />
+ </RadioList>
+ </>,
+ );
+ const outside = screen.getByText('before');
+ const optionB = screen.getByLabelText('Option B');
+ const optionC = screen.getByLabelText('Option C');
+ // A middle enabled radio (C) entered from outside is normalized to the
+ // first *enabled* radio (B) — the disabled Option A is skipped.
+ outside.focus();
+ optionC.focus();
+ expect(optionB).toHaveFocus();
+ });
+ });
});
diff --git a/packages/core/src/RadioList/RadioList.tsx b/packages/core/src/RadioList/RadioList.tsx
index 4fe6933dd4..aab1b6faa1 100644
--- a/packages/core/src/RadioList/RadioList.tsx
+++ b/packages/core/src/RadioList/RadioList.tsx
@@ -4,7 +4,7 @@
/**
* @file RadioList.tsx
- * @input Uses React useId, createContext, ReactNode, Field, InputStatus
+ * @input Uses React useId, useCallback, useRef, createContext, ReactNode, Field, InputStatus
* @output Exports RadioList component, RadioListProps, RadioListContext
* @position Core implementation; consumed by index.ts, tested by RadioList.test.tsx
*
@@ -16,7 +16,14 @@
* - /packages/cli/templates/blocks/components/RadioList/ (showcase blocks)
*/
-import React, {createContext, useId, useMemo, type ReactNode} from 'react';
+import React, {
+ createContext,
+ useCallback,
+ useId,
+ useMemo,
+ useRef,
+ type ReactNode,
+} from 'react';
import * as stylex from '@stylexjs/stylex';
import {spacingVars} from '../theme/tokens.stylex';
import {Field} from '../Field/Field';
@@ -41,8 +48,9 @@ export interface RadioListContextValue {
status?: InputStatus;
}
-export const RadioListContext =
- createContext<RadioListContextValue | null>(null);
+export const RadioListContext = createContext<RadioListContextValue | null>(
+ null,
+);
RadioListContext.displayName = 'RadioListContext';
const styles = stylex.create({
@@ -178,11 +186,95 @@ export function RadioList({
const descriptionID = useId();
const statusMessageID = useId();
+ const groupRef = useRef<HTMLDivElement>(null);
+
const contextValue = useMemo<RadioListContextValue>(
() => ({name, value, onChange, isDisabled, isRequired, size, status}),
[name, value, onChange, isDisabled, isRequired, size, status],
);
+ /**
+ * Make the tab stop deterministic when a radio group has no selected value.
+ *
+ * Native `<input type="radio">` groups (same `name`) implement roving
+ * tabindex for free: when a value is selected, that radio is the single tab
+ * stop and receives focus, so no correction is needed there. But the ARIA
+ * radio-group pattern (APG) also requires a deterministic tab stop when the
+ * group has *no* selection — and browsers disagree here. Chrome, when
+ * Shift+Tab moves focus backward into an unselected group, lands on the
+ * *last* radio; forward Tab lands on the *first*. To keep the entry point
+ * predictable we redirect focus:
+ * - forward entry → first enabled radio (APG default)
+ * - backward entry → last enabled radio (matches Chrome's backward tab)
+ *
+ * The redirect only runs when focus arrives from *outside* the group's own
+ * radios (guarded via `relatedTarget` containment). Moving between radios
+ * inside the group — arrow keys, clicks, programmatic focus of a sibling —
+ * is never hijacked.
+ */
+ const handleFocus = useCallback(
+ (e: React.FocusEvent<HTMLDivElement>) => {
+ // Only correct the no-selection case; a selected value already provides
+ // a deterministic native tab stop.
+ if (value !== '') {
+ return;
+ }
+
+ const group = groupRef.current;
+ if (!group) {
+ return;
+ }
+
+ // Ignore focus moving *within* the group. `relatedTarget` is the element
+ // losing focus; if it was inside the group, this is intra-group movement
+ // (arrow keys, clicking a sibling) and must not be hijacked. Some browsers
+ // report a null `relatedTarget`; fall back to checking whether the group
+ // already contained the active element before this focus landed.
+ const relatedTarget = e.relatedTarget as Node | null;
+ if (relatedTarget) {
+ if (group.contains(relatedTarget)) {
+ return;
+ }
+ } else if (
+ document.activeElement &&
+ document.activeElement !== e.target &&
+ group.contains(document.activeElement)
+ ) {
+ return;
+ }
+
+ const radios = Array.from(
+ group.querySelectorAll<HTMLInputElement>(
+ 'input[type="radio"]:not([disabled])',
+ ),
+ );
+ if (radios.length === 0) {
+ return;
+ }
+
+ const target = e.target as HTMLElement;
+ const targetIndex = radios.findIndex(radio => radio === target);
+ // Only correct when the focus target is one of our enabled radios (not a
+ // nested control such as end-content).
+ if (targetIndex === -1) {
+ return;
+ }
+
+ // Infer tab direction from which end the browser chose. On a backward
+ // (Shift+Tab) entry into an unselected group, browsers focus the *last*
+ // radio; keep it as the deterministic backward tab stop. Any other entry
+ // (forward Tab, or a browser that lands mid-group) is normalized to the
+ // *first* enabled radio, the APG default.
+ const isBackwardEntry = targetIndex === radios.length - 1;
+ const intended = isBackwardEntry ? radios[radios.length - 1] : radios[0];
+
+ if (target !== intended) {
+ intended.focus();
+ }
+ },
+ [value],
+ );
+
return (
<Field
ref={ref}
@@ -211,8 +303,10 @@ export function RadioList({
className={className}
style={style}>
<div
+ ref={groupRef}
role="radiogroup"
aria-label={label}
+ onFocus={handleFocus}
aria-describedby={
[
description ? descriptionID : null,
@@ -230,9 +324,7 @@ export function RadioList({
orientation === 'vertical' ? styles.vertical : styles.horizontal,
),
)}>
- <RadioListContext value={contextValue}>
- {children}
- </RadioListContext>
+ <RadioListContext value={contextValue}>{children}</RadioListContext>
</div>
</Field>
);