feat: modernize RadioButton for MD3 by burczu · Pull Request #5007 · callstack/react-native-paper

burczu · 2026-06-19T12:05:23Z

Motivation

RadioButton still shipped as two platform-specific implementations (RadioButtonAndroid, RadioButtonIOS) with the iOS variant rendering a checkmark glyph rather than a Material radio. This is inconsistent with the rest of the v6 MD3 work (Checkbox, Switch, TextInput, FAB) and diverges from the M3 radio button spec.

This PR unifies RadioButton into a single MD3 component that mirrors the modernized Checkbox structure (single component, tokens.ts, error prop, accessible={false} inner control), without pulling in Checkbox's reanimated/focus-ring machinery (out of scope — radio ships with none today).

Related issue

Closes #4938

What changed

Unified component — merged RadioButtonAndroid + RadioButtonIOS into a single MD3 RadioButton (Android impl as base). Dropped RadioButton.Android, RadioButton.IOS, RadioButtonIOS, and the RadioButton.Item mode prop.
Tokens — new RadioButton/tokens.ts (MD3 dims 20/10/2 + color roles); colors resolved via tokens in utils.
error prop — added to RadioButton and RadioButton.Item (ring + dot use theme.colors.error; disabled/custom colors take precedence).
Single animation path (reanimated) — collapsed two RN Animated.Values into one shared value and migrated to react-native-reanimated (matching Checkbox): dot scales in with overshoot on selection, keyed on checked so it also animates inside a RadioButton.Group. Uses theme.motion MD3 duration/easing tokens and respects reduce-motion.
Disabled opacity — the control now dims to 38% (selectionControlOpacity was previously computed but never applied).
Group perf — memoized the provider value + stabilized onValueChange with use-latest-callback; consumers switched from Context.Consumer to useContext.
Item a11y — inner control is accessible={false} + container importantForAccessibility="no-hide-descendants", so a screen reader sees one radio per row; dropped per-radio accessibilityLiveRegion; labelMaxFontSizeMultiplier=1.5 + ${testID}-text for CheckboxItem parity.
Docs/examples — updated examples (Group/Item, leading/trailing, error checked+unchecked, disabled); removed the iOS-mode demo and the RadioButtonAndroid/RadioButtonIOS doc pages.

Breaking changes

Removed RadioButton.Android, RadioButton.IOS, RadioButtonIOS (and RadioButtonAndroidProps/RadioButtonIOSProps exports).
Removed the RadioButton.Item mode prop.
error prop added (no visual change for existing usage).

Test plan

yarn typescript, yarn lint, yarn test (snapshots updated) — green.
yarn --cwd docs build — green.
Manually verified on iOS sim, Android emulator, and web: single selection, dot scale-in (standalone and in a Group), error (checked/unchecked), disabled dimming, leading/trailing, ripple, single a11y node per Item row.

Videos

radio_ios.mp4

radio_android.mp4

radio_web.mp4

satya164 · 2026-06-28T16:22:07Z

can you rebase the PR against main?

Copilot

Pull request overview

This PR modernizes RadioButton for Material Design 3 by replacing the prior platform-specific implementations with a single unified component, introducing MD3 token-based sizing/color resolution, and aligning behavior (animation, error/disabled states, a11y, and group performance) with the library’s other MD3 selection controls.

Changes:

Unifies RadioButton into a single MD3 implementation (removing RadioButton.Android, RadioButton.IOS, and the RadioButton.Item mode prop) and migrates selection animation to react-native-reanimated.
Adds MD3 radio tokens + error support, applies disabled opacity consistently, and updates selection-control color resolution to use tokenized theme roles.
Improves RadioButton.Group context stability and updates tests/examples/docs accordingly (including removing platform-specific docs pages).

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/index.tsx	Removes exported platform-specific RadioButton prop types.
src/components/RadioButton/utils.ts	Updates selection-control color resolution to use RadioButton tokens and removes iOS-specific helper.
src/components/RadioButton/tokens.ts	Introduces MD3 radio sizing + color-role tokens.
src/components/RadioButton/RadioButtonItem.tsx	Removes `mode`, adds `error`, switches to `useContext`, and adjusts a11y/testID behavior.
src/components/RadioButton/RadioButtonGroup.tsx	Memoizes context value and stabilizes `onValueChange` with `use-latest-callback`.
src/components/RadioButton/RadioButtonAndroid.tsx	Deletes old Android-specific implementation.
src/components/RadioButton/RadioButtonIOS.tsx	Deletes old iOS-specific implementation.
src/components/RadioButton/RadioButton.tsx	Implements unified MD3 RadioButton with Reanimated dot-scale animation, tokenized sizes/colors, and updated a11y behavior.
src/components/RadioButton/index.ts	Removes `.Android`/`.IOS` static exports from `RadioButton`.
src/components/tests/RadioButton/utils.test.tsx	Updates tests to cover `getSelectionControlColor` including error/checked/unchecked cases.
src/components/tests/RadioButton/RadioButtonItem.test.tsx	Removes platform-mode tests and adds a11y single-node assertion.
src/components/tests/RadioButton/RadioButtonGroup.test.tsx	Adds test asserting stable context object across unrelated parent rerenders.
src/components/tests/RadioButton/RadioButton.test.tsx	Simplifies snapshots to single unified RadioButton implementation.
src/components/tests/RadioButton/snapshots/RadioButtonItem.test.tsx.snap	Updates snapshots for new unified control + a11y changes.
src/components/tests/RadioButton/snapshots/RadioButtonGroup.test.tsx.snap	Updates snapshots for new unified control rendering.
src/components/tests/RadioButton/snapshots/RadioButton.test.tsx.snap	Updates snapshots for unified control rendering.
example/src/Examples/RadioButtonItemExample.tsx	Updates example to remove mode variants and demonstrate error/disabled states.
example/src/Examples/RadioButtonGroupExample.tsx	Updates example usage to `RadioButton` (no platform statics).
example/src/Examples/RadioButtonExample.tsx	Updates example states, adds error demos, and adjusts disabled label styling.
docs/versioned_docs/version-6.x/components/RadioButton/RadioButtonItem.mdx	Removes documentation for the deleted `mode` prop.
docs/versioned_docs/version-6.x/components/RadioButton/RadioButtonIOS.mdx	Removes iOS-specific docs page.
docs/versioned_docs/version-6.x/components/RadioButton/RadioButtonAndroid.mdx	Removes Android-specific docs page.
docs/docusaurus.config.js	Removes nav entries for the deleted platform-specific docs pages.

burczu · 2026-07-03T11:28:53Z

+        <Text
+          variant={labelVariant}
+          testID={`${testID}-text`}
+          style={[styles.label, computedStyle, labelStyle]}
+          maxFontSizeMultiplier={labelMaxFontSizeMultiplier}
+        >


burczu · 2026-07-03T11:29:08Z

  /**
   * Function to execute on press.
   */
-  onPress?: (e: GestureResponderEvent) => void;
+  onPress?: (param?: any) => void;
  /**


burczu · 2026-07-03T11:28:59Z

+  return (
+    <TouchableRipple
+      {...rest}
+      borderless
+      onPress={(event) => {
+        handlePress({
+          onPress,
+          onValueChange: context?.onValueChange,
+          value,
+          event,
+        });
+      }}
+      disabled={disabled}
+      {...accessibilityProps}
+      style={styles.container}
+      testID={testID}
+      theme={theme}
+    >


- Fix accessibilityLabel variable reference (ariaLabel, not accessibilityLabel) - Make sync render() calls async in RadioButton and RadioButtonItem tests - Await rerender() in RadioButtonGroup stability test - Use screen.queryAllByRole instead of destructuring from render result - Update snapshots to reflect accessibilityRole instead of role prop

Nested ternary indentation left misaligned after conflict resolution.

RadioButtonAndroid and RadioButtonIOS were removed but the navigation index still referenced them, breaking the docs build.

RadioButtonAndroid and RadioButtonIOS source mappings caused the docs build to fail with ENOENT since the files no longer exist.

- Restore onPress type to (e: GestureResponderEvent) => void to match TouchableRipple - Merge consumer style with container style, handling function-style props - Guard RadioButtonItem label testID to avoid "undefined-text" when testID is not provided

MikitasK · 2026-08-24T11:57:49Z

+  // The outer TouchableRipple is the interactable element + a11y radio; the
+  // inner control is purely visual, so exclude it from the a11y tree to
+  // avoid duplicate `checked` states.
+  const radioButton = <RadioButton {...radioButtonProps} accessible={false} />;


what about preventing visual-only radio from receiving keyboard focus?

accessible={false} removes its accessibility semantics, but updated snapshot still shows focusable={true} (source)

additionally, react-native-web defaults enabled Pressable to tabIndex={0} (RNW sourcecode), leaving unlabeled second tab stop inside RadioButton.Item

so what about this change?

Suggested change

const radioButton = <RadioButton {...radioButtonProps} accessible={false} />;

const radioButton = <RadioButton {...radioButtonProps} accessible={false} focusable={false} tabIndex={-1} />;

MikitasK · 2026-08-24T12:04:21Z

+const sizes = {
+  ringSize: 20,
+  dotSize: 10,
+  outlineWidth: 2,
+} as const;


what about adding an explicit state-layer size token & sizing touchable accordingly?

current 20dp ring with 8dp margins produces 36dp state layer, while MD3 defines radio state layer as 40dp.
modernized Checkbox component already uses the same 40dp state-layer token (source)

so could we change it to:

Suggested change

const sizes = {

ringSize: 20,

dotSize: 10,

outlineWidth: 2,

} as const;

const sizes = {

ringSize: 20,

dotSize: 10,

outlineWidth: 2,

stateLayerSize: 40,

} as const;

and use like that in RadioButton.tsx:

const { ringSize, dotSize, outlineWidth: OUTLINE_WIDTH, stateLayerSize, } = RadioButtonTokens; const styles = StyleSheet.create({ container: { width: stateLayerSize, height: stateLayerSize, borderRadius: stateLayerSize / 2, alignItems: 'center', justifyContent: 'center', }, radio: { height: ringSize, width: ringSize, borderRadius: ringSize / 2, borderWidth: OUTLINE_WIDTH, }, });

…into feat/radio-button-md3 # Conflicts: # src/components/RadioButton/RadioButtonAndroid.tsx # src/components/RadioButton/RadioButtonIOS.tsx # src/components/RadioButton/RadioButtonItem.tsx

MikitasK

updated radio-button state layer to MD3 specified 40dp size while keeping visible ring centered at 20dp
added reusable stateLayerSize token & removed previous margin-based state-layer sizing
made nested visual control inside RadioButton.Item non-focusable with focusable={false} and tabIndex={-1} keeping outer item as the only interactive radio
added regression coverage for 40dp state layer & updated affected accessibility & component snapshots

JKobrynski · 2026-08-25T09:13:40Z

+  const accessibilityProps =
+    rest.accessible === false
+      ? {}
+      : {
+          accessibilityRole: 'radio' as const,
+          accessibilityState: { disabled: !!disabled, checked },
+        };


- accessibilityRole: 'radio' as const, - accessibilityState: { disabled: !!disabled, checked }, + role: 'radio' as const, + 'aria-disabled': !!disabled, + 'aria-checked': checked,

466d9c608 (#5005) moved the library to aria-* and src/ on main has none of these props left. Same revert at RadioButtonItem.tsx:207-212 (accessibilityLabel / Role / State) and RadioButtonGroup.tsx:69 (accessibilityRole="radiogroup"; main has role). Checkbox.tsx:249-256 is the shape to copy under the identical rest.accessible === false guard, and CheckboxItem.tsx:157-160 for the row. Snapshots need regenerating after.

JKobrynski · 2026-08-25T09:14:29Z

+        {checked ? (
+          <View style={[StyleSheet.absoluteFill, styles.radioContainer]}>
+            <Animated.View
+              style={[
+                styles.dot,
+                { backgroundColor: selectionControlColor },
+                dotAnimatedStyle,
+              ]}
+            />
+          </View>
+        ) : null}


The StyleSheet.absoluteFill + radioContainer wrapper only existed because the old code animated borderWidth. The outline is a constant now, so it can go: put alignItems: 'center' / justifyContent: 'center' on styles.radio, render the Animated.View dot directly as its child, and drop styles.radioContainer.

JKobrynski · 2026-08-27T08:47:31Z

@MikitasK is this ready for another review?

burczu marked this pull request as ready for review June 19, 2026 12:07

burczu requested a review from satya164 June 19, 2026 12:15

satya164 added the Contributor: Internal label Jun 22, 2026

satya164 requested a review from Copilot June 28, 2026 16:21

Copilot started reviewing on behalf of satya164 June 28, 2026 16:22 View session

Copilot AI reviewed Jun 28, 2026

View reviewed changes

burczu added 8 commits July 2, 2026 14:17

refactor(radio-button): merge platform variants into one MD3 component

6221077

feat(radio-button): add MD3 tokens, error state, single animation path

a155b74

perf(radio-button): memoize group context, switch to useContext

015baf4

fix(radio-button): single a11y node per item, error + parity cleanup

9649647

docs(radio-button): update example + drop platform variant docs

9e4a668

fix(radio-button): apply disabled opacity, animate group selection

d9f3973

docs(radio-button): dim disabled labels, add unchecked error examples

ee00e84

refactor(radio-button): migrate dot animation to reanimated

c0e1c18

burczu force-pushed the feat/radio-button-md3 branch from cb74fc8 to c0e1c18 Compare July 2, 2026 12:25

burczu added 5 commits July 2, 2026 14:33

fix(radio-button): fix prettier formatting in utils.ts

2b4eebb

Nested ternary indentation left misaligned after conflict resolution.

docs(radio-button): drop deleted pages from _meta.json

1d1ea02

RadioButtonAndroid and RadioButtonIOS were removed but the navigation index still referenced them, breaking the docs build.

docs(radio-button): remove deleted components from docs config

3c226a1

RadioButtonAndroid and RadioButtonIOS source mappings caused the docs build to fail with ENOENT since the files no longer exist.

MikitasK reviewed Aug 24, 2026

View reviewed changes

MikitasK added 3 commits August 24, 2026 17:19

fix: prevent nested item control from receiving focus

a1a3e75

fix: use 40dp MD3 state layer

feb9a54

Merge branch 'main' of https://github.com/callstack/react-native-paper …

5554631

…into feat/radio-button-md3 # Conflicts: # src/components/RadioButton/RadioButtonAndroid.tsx # src/components/RadioButton/RadioButtonIOS.tsx # src/components/RadioButton/RadioButtonItem.tsx

MikitasK approved these changes Aug 24, 2026

View reviewed changes

JKobrynski requested changes Aug 25, 2026

View reviewed changes

refactor: address review feedback

12644a8

	const radioButton = <RadioButton {...radioButtonProps} accessible={false} />;
	const radioButton = <RadioButton {...radioButtonProps} accessible={false} focusable={false} tabIndex={-1} />;

Uh oh!

Uh oh!

Conversation

burczu commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Related issue

What changed

Breaking changes

Test plan

Videos

Uh oh!

satya164 commented Jun 28, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MikitasK left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JKobrynski commented Aug 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

burczu commented Jun 19, 2026 •

edited

Loading