Add 'auto' to ColorSchemeOverride, deprecate 'unspecified'

Summary:
NOTE: 👋🏻 **This is an RFC**, additional and separate to the previous 2 diffs. Looking for feedback :)

Proposes an API tweak to `Appearance.setColorScheme()` to make it more idiomatic/understandable.

- Aligns with the CSS `color-scheme` property vocabulary, where `auto` means "defer to the system preference".
- Replaces the ambiguous `unspecified` (now deprecated), which gave no indication of the resulting behaviour.

See also:
- History of this API + return type narrowing in D102527387.
- Extended docs + diagram in https://github.com/facebook/react-native-website/pull/5060.

**Alternative names considered**

- `'reset'` - Implies reversing a change, not deferring to system
- `'inherit'` -  Weak — CSS inherit is element→parent, not app→OS

Changelog:
[General][Deprecated] - `Appearance.setColorScheme('unspecified')` is deprecated, use `'auto'` instead.

Reviewed By: cipolleschi

Differential Revision: D103841988

fbshipit-source-id: 474d0925ce9ee0ab79f87d0ff9ae86ae56ceb0aa
This commit is contained in:
Alex Hunt authored and meta-codesync[bot] committed 2026-05-07 01:54:35 -07:00
1 parent ef6463c25d
commit 91702e50fe
7 files changed
+19 -16

No files matched your search

+7 -3
View File
@@ -11,7 +11,11 @@ import {NativeEventSubscription} from '../EventEmitter/RCTNativeAppEventEmitter'
type ColorSchemeName = 'light' | 'dark';
type ColorSchemeOverride = ColorSchemeName | 'unspecified';
type ColorSchemeOverride =
| ColorSchemeName
| 'auto'
/** @deprecated Use 'auto' instead */
| 'unspecified';
export namespace Appearance {
type AppearancePreferences = {
@@ -36,8 +40,8 @@ export namespace Appearance {
/**
* Force the application to always adopt a light or dark interface style. Pass
* `'unspecified'` to reset and follow the system default (removes any
* override). This does not affect the system UI, only the application.
* `'auto'` to reset and follow the system default (removes any override).
* This does not affect the system UI, only the application.
*/
export function setColorScheme(scheme: ColorSchemeOverride): void;
+3 -3
View File
@@ -107,8 +107,8 @@ export function getColorScheme(): ColorSchemeName | null {
/**
* Force the application to always adopt a light or dark interface style. Pass
* `'unspecified'` to reset and follow the system default (removes any
* override). This does not affect the system UI, only the application.
* `'auto'` to reset and follow the system default (removes any override).
* This does not affect the system UI, only the application.
*/
export function setColorScheme(colorScheme: ColorSchemeOverride): void {
const state = getState();
@@ -117,7 +117,7 @@ export function setColorScheme(colorScheme: ColorSchemeOverride): void {
NativeAppearance.setColorScheme(colorScheme);
state.appearance = {
colorScheme:
colorScheme === 'unspecified'
colorScheme === 'auto' || colorScheme === 'unspecified'
? NativeAppearance.getColorScheme()
: colorScheme,
};
@@ -494,6 +494,7 @@ RCT_ENUM_CONVERTER(
RCT_ENUM_CONVERTER(
UIUserInterfaceStyle,
(@{
@"auto" : @(UIUserInterfaceStyleUnspecified),
@"unspecified" : @(UIUserInterfaceStyleUnspecified),
@"light" : @(UIUserInterfaceStyleLight),
@"dark" : @(UIUserInterfaceStyleDark),
@@ -87,6 +87,7 @@ constructor(
when (style) {
"dark" -> AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_YES)
"light" -> AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_NO)
"auto",
"unspecified" ->
AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_FOLLOW_SYSTEM)
}
+3 -3
View File
@@ -4,7 +4,7 @@
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @generated SignedSource<<04955f1605996352fa3f3a3fc86ba937>>
* @generated SignedSource<<eeffa8d1c270f98debd70024251b4a1a>>
*
* This file was generated by scripts/js-api/build-types/index.js.
*/
@@ -1859,7 +1859,7 @@ declare namespace CodegenTypes {
}
declare type ColorListenerCallback = (value: ColorValue) => unknown
declare type ColorSchemeName = "dark" | "light"
declare type ColorSchemeOverride = "dark" | "light" | "unspecified"
declare type ColorSchemeOverride = "auto" | "dark" | "light" | "unspecified"
declare type ColorValue = ____ColorValue_Internal
declare type ComponentProvider = () => React.ComponentType<any>
declare type ComponentProviderInstrumentationHook = (
@@ -6073,7 +6073,7 @@ export {
AppState, // 12012be5
AppStateEvent, // 80f034c3
AppStateStatus, // 447e5ef2
Appearance, // 0e9bf4fe
Appearance, // 83e9641a
AutoCapitalize, // c0e857a0
BackHandler, // f139fc69
BackPressEventName, // 4620fb76
@@ -14,7 +14,7 @@ import * as TurboModuleRegistry from '../../../../Libraries/TurboModule/TurboMod
export type ColorSchemeName = 'light' | 'dark';
export type ColorSchemeOverride = 'light' | 'dark' | 'unspecified';
export type ColorSchemeOverride = 'light' | 'dark' | 'auto' | 'unspecified';
export type AppearancePreferences = {
colorScheme: ColorSchemeName,
@@ -136,8 +136,8 @@ const ColorShowcase = (props: {themeName: string}) => (
const ToggleNativeAppearance = () => {
const [nativeColorScheme, setNativeColorScheme] = useState<
ColorSchemeName | 'unspecified',
>('unspecified');
ColorSchemeName | 'auto',
>('auto');
const colorScheme = useColorScheme();
useEffect(() => {
@@ -156,10 +156,7 @@ const ToggleNativeAppearance = () => {
title="Set to dark"
onPress={() => setNativeColorScheme('dark')}
/>
<Button
title="Unset"
onPress={() => setNativeColorScheme('unspecified')}
/>
<Button title="Auto" onPress={() => setNativeColorScheme('auto')} />
</View>
);
};