A framework for building native applications using React
Remove 'unspecified' from ColorSchemeName (#56686)
Summary:
Pull Request resolved: https://github.com/facebook/react-native/pull/56686
Removes `'unspecified'` from the return type of `Appearance.getColorScheme()` and `useColorScheme()`, splitting the setter input into a separate `ColorSchemeOverride` type. This resolves a longstanding misalignment between what native returns and what the types promise.
**Motivation**
`'unspecified'` is only meaningful as an input to `setColorScheme()` — neither iOS nor Android ever returns it from `getColorScheme()`. When `setColorScheme('unspecified')` is called, the JS layer re-queries the native module and caches the resolved system value.
After this change:
- `Appearance.getColorScheme()` returns `'light' | 'dark'` (no longer `'unspecified'`)
- `Appearance.setColorScheme()` receives `'light' | 'dark' | 'unspecified'`
Paired with docs updates:
- https://github.com/facebook/react-native-website/pull/5060
- https://github.com/facebook/react-native-website/pull/5069
**History of this API**
- The TurboModule spec originally typed these methods as plain `string` because codegen didn't support union types (T52919652).
- When support landed, D63681874 upgraded to `ColorSchemeName = 'light' | 'dark' | 'unspecified'` — a type-level cleanup that inadvertently widened return types to include `'unspecified'`, a value native never returns. This caused `$FlowFixMe` suppressions across downstream callers.
- D80705652 later aligned the `.d.ts` and fixed a bug where `setColorScheme('unspecified')` threw an incorrect invariant.
Changelog:
[General][Breaking] - `useColorScheme()` no longer returns `'unspecified'` (this was always the case, but is a breaking type change)
Reviewed By: cipolleschi
Differential Revision: D102527387
fbshipit-source-id: 3fc19add59450cb07b9d0a962c63c4fa208faa63 A
Alex Hunt committed
8ac88f481a51cec28adfe985382ac7b3648921e5
Parent: ba204fa
Committed by meta-codesync[bot] <215208954+meta-codesync[bot]@users.noreply.github.com>
on 5/7/2026, 8:54:35 AM