feat(checkbox): add error state via MD3 error tokens

[fabriziocucci]

Summary

Adds an error?: boolean prop to Checkbox, CheckboxAndroid and CheckboxIOS. When true, the outline (unchecked) and container (checked / indeterminate) render with theme.colors.error; the checked / indeterminate icon uses theme.colors.onError on Android and theme.colors.error on iOS.

This addresses one bullet from #4937 / discussion #4949 (Checkbox section, "Error state not implemented"):

Error state not implemented. Spec defines error tokens for unselected error outline and selected error container (md.sys.color.error), and onError for the error icon.

MD3 spec reference: https://m3.material.io/components/checkbox/specs

Behavior

When error={true}:

State	Unselected	Selected	Indeterminate
Outline / container	theme.colors.error	theme.colors.error	theme.colors.error
Icon	(n/a, outline only)	white check inside red container (Android) / red check (iOS)	white dash inside red container (Android) / red dash (iOS)

Composition with existing props (precedence rules)

1. disabled wins: disabled tokens override error entirely. Matches MD3 spec (disabled is the highest-precedence visual state).
2. color wins for checked: an explicit color prop overrides the error token for the checked container.
3. Indeterminate state honors error via the unchecked-color path on Android. It does NOT honor a color override (pre-existing v6 behavior, not introduced by this PR). Tracked separately for a focused follow-up.
4. uncheckedColor wins for unchecked outline only: an explicit uncheckedColor overrides the error token for the unchecked outline; checked / indeterminate states still use the error container.
5. No error prop = no behavior change: the prop defaults to undefined, so existing usages are byte-for-byte identical.

Implementation

• src/components/Checkbox/utils.ts: extended getAndroidCheckedColor, getAndroidUncheckedColor, getAndroidSelectionControlColor, getIOSCheckedColor and getSelectionControlIOSColor with an optional error parameter. The error branch sits between custom* (highest precedence) and the theme defaults (lowest), preserving existing behavior when error is unset.
• src/components/Checkbox/Checkbox.tsx: added error?: boolean to Props with JSDoc.
• src/components/Checkbox/CheckboxAndroid.tsx: added error to Props, destructured from the component's args, forwarded to getAndroidSelectionControlColor.
• src/components/Checkbox/CheckboxIOS.tsx: same pattern as Android.

CheckboxItem.tsx is not modified in this PR. That's a follow-up. CheckboxItem would just need to add error?: boolean to its Props and forward to the embedded <Checkbox>. Splitting it keeps this PR focused on the core component.

Testing

Visually verified on iOS Simulator (iPhone 17 Pro, iOS 18) and Android Emulator (Pixel 9, API 35) across light and dark themes using a standalone Expo app with the patch applied via patch-package.

Unit tests for the new error path added in src/components/__tests__/Checkbox/utils.test.tsx (10 new cases on top of the existing 10):

• Android: error checked / unchecked / dark mode / disabled-wins / customColor-wins / customUncheckedColor-wins
• iOS: error / dark mode / disabled-wins / customColor-wins

Screenshots:

iOS

Theme	Before	After
Light
Dark

Android

Theme	Before	After
Light
Dark

A few observations:

• The dark-mode "after" screenshots show salmon-red (#FFB4AB-ish) rather than the light-mode bright red (#B3261E). That's correct. Both come from theme.colors.error, which MD3 specifies separately for the two themes. The patch is token-based so any custom theme passed via PaperProvider Just Works.
• iOS Checkbox renders no visible box for the unchecked state today (separate concern from this PR, flagged in React Native Paper: MD3 Component Review #4949's Checkbox section), so the "error outline" on iOS unchecked is visually absent. The patch still sets the right color value via getIOSCheckedColor; you'd see it once the unchecked box is added in a future PR.
• The composition cases (error + disabled, error + color, error + uncheckedColor) were each verified visually.

What's NOT in this PR

These were considered and intentionally deferred (each could be its own PR):

• Visible unchecked box on iOS (separate React Native Paper: MD3 Component Review #4949 bullet)
• theme.colors.errorContainer support (would need an additional containerColor prop / API change)
• Hover state (also missing from react-native-paper per React Native Paper: MD3 Component Review #4949 General Notes)
• Shape tokens (theme.shapes.full etc., also React Native Paper: MD3 Component Review #4949 General Notes)
• Removing the MD2-style bounce animation on Android (React Native Paper: MD3 Component Review #4949 Checkbox > Behavior bullet)

Happy to discuss bundling any of these into this PR if you'd prefer, or to send follow-ups.

Conventional commit

feat(checkbox): add error state via MD3 error tokens

Related

• Issue: refactor(checkbox): improve MD3 behavior and simplify selection API #4937
• Discussion: React Native Paper: MD3 Component Review #4949 (Checkbox section, "Error state not implemented" bullet)
• MD3 spec: https://m3.material.io/components/checkbox/specs
• Material Components reference impl: https://github.com/material-components/material-components-android

cc @adrcotfas

[callstack-bot]

Hey @fabriziocucci, thank you for your pull request 🤗. The documentation from this branch can be viewed here.

[Copilot]

Pull request overview

Adds an error?: boolean prop to the core Checkbox components to support an MD3-style error visual state by sourcing colors from theme.colors.error (and intended onError for Android icon per PR description), implemented via shared selection-control color utilities.

Changes:

• Extended Checkbox selection-control color utilities to optionally return theme.colors.error for checked/unchecked states.
• Added error?: boolean to Checkbox, CheckboxAndroid, and CheckboxIOS props and forwarded it into the color utility functions.
• Updated component prop documentation (JSDoc) to describe error-state precedence.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
src/components/Checkbox/utils.ts	Adds error handling to Android/iOS color helpers used by Checkbox (and shared selection-control helpers).
src/components/Checkbox/CheckboxAndroid.tsx	Adds error prop and forwards it into Android selection-control color computation.
src/components/Checkbox/CheckboxIOS.tsx	Adds error prop and forwards it into iOS checked color computation.
src/components/Checkbox/Checkbox.tsx	Adds error to the public Checkbox prop type/docs and forwards to platform implementations.

Comments suppressed due to low confidence (1)

src/components/Checkbox/CheckboxAndroid.tsx:119

• The implementation currently sets selectionControlColor to theme.colors.error when error is true, and that same value is used to tint the Android icon. This doesn’t match the stated behavior/spec of using theme.colors.onError for the check/dash when the container is error. If you want MD3 parity here, the icon color likely needs to be computed separately (e.g., container uses error, glyph uses onError) rather than using a single selectionControlColor for everything.

  const { selectionControlColor, selectionControlOpacity } =
    getAndroidSelectionControlColor({
      theme,
      disabled,
      checked,
      customColor: rest.color,
      customUncheckedColor: rest.uncheckedColor,
      error,
    });

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[fabriziocucci]

Re: the suppressed comment about selectionControlColor not using theme.colors.onError for the glyph. Current rendering uses MaterialCommunityIcon glyphs (checkbox-marked / minus-box) where the check/dash is transparent negative space inside a filled box. Tinting with theme.colors.error produces "red container, surface-color check", equivalent to MD3 container=error + glyph=onError on light surfaces and readable on dark (see screenshots).

Proper compositing (background View + onError-tinted glyph OR different icon family) is a larger architectural change tracked separately under broader #4949 Checkbox rework (state layer, shape tokens, 18dp icon size).

Out of scope for this PR.

[fabriziocucci]

cc @satya164

[adrcotfas]

Some general comments:

• Since you're touching this component and it's not a large one, let's finalize the modernization in one PR
• Please reuse the same UI between platforms as per MD specs
• Implement the hover and focus states too (new tokens for focus will be added here: feat: improve structure of ref and sys tokens; add useFocusVisible hook #4952)
• Improve the Checkbox example page with a parent/child checkbox relationship; parent's state(can be indeterminate when at least one child is toggled off) depends on the state of the children.
• It's a good moment to replace the checkbox icons with actual drawing so we can fully respect the tokens from the specs
• Adding a subtle animation like on native would be nice; we already have Reanimated integrated and motion tokens; I can share the native animation implementation if needed.

Edit: I'm fine with handling these in other PRs.