From 91702e50fe077ae73ab152da18719d6df98cb71f Mon Sep 17 00:00:00 2001 From: Alex Hunt Date: Thu, 7 May 2026 01:54:35 -0700 Subject: [PATCH] Add 'auto' to ColorSchemeOverride, deprecate 'unspecified' MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .../react-native/Libraries/Utilities/Appearance.d.ts | 10 +++++++--- .../react-native/Libraries/Utilities/Appearance.js | 6 +++--- packages/react-native/React/Base/RCTConvert.mm | 1 + .../react/modules/appearance/AppearanceModule.kt | 1 + packages/react-native/ReactNativeApi.d.ts | 6 +++--- .../specs_DEPRECATED/modules/NativeAppearance.js | 2 +- .../js/examples/Appearance/AppearanceExample.js | 9 +++------ 7 files changed, 19 insertions(+), 16 deletions(-) diff --git a/packages/react-native/Libraries/Utilities/Appearance.d.ts b/packages/react-native/Libraries/Utilities/Appearance.d.ts index c37a0ea577d..153f0386fdf 100644 --- a/packages/react-native/Libraries/Utilities/Appearance.d.ts +++ b/packages/react-native/Libraries/Utilities/Appearance.d.ts @@ -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; diff --git a/packages/react-native/Libraries/Utilities/Appearance.js b/packages/react-native/Libraries/Utilities/Appearance.js index 4af8fe2e6b3..936b03f9385 100644 --- a/packages/react-native/Libraries/Utilities/Appearance.js +++ b/packages/react-native/Libraries/Utilities/Appearance.js @@ -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, }; diff --git a/packages/react-native/React/Base/RCTConvert.mm b/packages/react-native/React/Base/RCTConvert.mm index 0aacbd85610..9400163dd81 100644 --- a/packages/react-native/React/Base/RCTConvert.mm +++ b/packages/react-native/React/Base/RCTConvert.mm @@ -494,6 +494,7 @@ RCT_ENUM_CONVERTER( RCT_ENUM_CONVERTER( UIUserInterfaceStyle, (@{ + @"auto" : @(UIUserInterfaceStyleUnspecified), @"unspecified" : @(UIUserInterfaceStyleUnspecified), @"light" : @(UIUserInterfaceStyleLight), @"dark" : @(UIUserInterfaceStyleDark), diff --git a/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/modules/appearance/AppearanceModule.kt b/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/modules/appearance/AppearanceModule.kt index 65f1088ef51..4028e2a9a20 100644 --- a/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/modules/appearance/AppearanceModule.kt +++ b/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/modules/appearance/AppearanceModule.kt @@ -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) } diff --git a/packages/react-native/ReactNativeApi.d.ts b/packages/react-native/ReactNativeApi.d.ts index a2538b661fd..6e7dd111ae4 100644 --- a/packages/react-native/ReactNativeApi.d.ts +++ b/packages/react-native/ReactNativeApi.d.ts @@ -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<> * * 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 declare type ComponentProviderInstrumentationHook = ( @@ -6073,7 +6073,7 @@ export { AppState, // 12012be5 AppStateEvent, // 80f034c3 AppStateStatus, // 447e5ef2 - Appearance, // 0e9bf4fe + Appearance, // 83e9641a AutoCapitalize, // c0e857a0 BackHandler, // f139fc69 BackPressEventName, // 4620fb76 diff --git a/packages/react-native/src/private/specs_DEPRECATED/modules/NativeAppearance.js b/packages/react-native/src/private/specs_DEPRECATED/modules/NativeAppearance.js index e1f8835be6d..24293ff900a 100644 --- a/packages/react-native/src/private/specs_DEPRECATED/modules/NativeAppearance.js +++ b/packages/react-native/src/private/specs_DEPRECATED/modules/NativeAppearance.js @@ -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, diff --git a/packages/rn-tester/js/examples/Appearance/AppearanceExample.js b/packages/rn-tester/js/examples/Appearance/AppearanceExample.js index 06f315af801..62bc5f9c297 100644 --- a/packages/rn-tester/js/examples/Appearance/AppearanceExample.js +++ b/packages/rn-tester/js/examples/Appearance/AppearanceExample.js @@ -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')} /> -