Platform specific colors via PlatformColor

[turnrye]

Edit: A more general proposal has been posted by @tom-un to support generic platform defined colors. Jump to that proposal. That proposal now supersedes the one in this top post.

Original Proposal

### Introduction

Android Q introduced a Dark theme across the system and applications. From their presentation, "Users will expect apps to have a dark theme". The way we do styling on RN today isn't directly compatible with their solution, but it's close.

The Core of It

I opened facebook/react-native#24790 with a proposed solution, but it admittedly had some issues:

• It was on Platform, but it's more prone to change than the rest of those values
• It closely followed Android's implementation, but doesn't anticipate what iOS or out-of-tree platforms might use
• Android normally recreates the activities when this value changes, but that isn't a safe way to lead to re-rendering (which would be common if the user has enabled it by time-of-day or as part of battery saver)

Discussion Points

• What's a better home for this than Platform? While it is a device setting, it's not quite in the same class as things like Version.
• Should we stick with the interface that we know (Android's) or anticipate a more universal solution using perhaps https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme

[acoates-ms]

@tom-un, might be able to fill in some more details. But for our macOS RN platform we extended the valid values for color. So you can specify either system colors, or be able to specify colors that change based on the native theme Something like:

<View background={{dynamic:{light: 'red', dark:'pink'}}} />
<View background={semantic: "windowBackgroundColor"} />

I believe there was some plan to look at contributing that back for iOS too.

[mmmulani]

thanks for starting the proposal!

Android normally recreates the activities when this value changes, but that isn't a safe way to lead to re-rendering (which would be common if the user has enabled it by time-of-day or as part of battery saver)

from my reading of the docs, it seem like this changed and depending on how it's implemented, activities might not be recreated when the system theme changed. Because of that, I think a pattern similar to how we treat orientation makes more sense

[turnrye]

@acoates-ms will you describe that a bit more? That seems like a good solution for brownfield applications too where they need robust native themes. It's a solution that helps beyond just this light/dark mode use case and instead pushes themes into the native platform, which may or may not be desirable.

@mmmulani that makes a lot of sense. It'd also give more flexibility for other platforms as well that might not recreate automatically.

[elicwhite]

Also worth mentioning that we recently added an accessibility prop on View called accessibilityIgnoresInvertColors. This is used in iOS inverted mode to keep things like images from being inverted. At Google IO they mentioned that Android will have support for auto dark mode'ing 😄 apps but that images can look weird then. I imagine Android has a similar flag for this. A PR that wires up accessibilityIgnoresInvertColors to the new Android thing would be much appreciated.

[turnrye]

@TheSavior I experimented with that some -- it works relatively well, but there are definitely places where people are going to need to manually handle this. In our apps that's the case, and when I tried some other popular RN apps it was mixed as well.

I'll definitely submit that PR -- wasn't familiar with that. I don't think it directly addresses this discussion though.

[necolas]

• https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme
• https://medium.freecodecamp.org/how-to-detect-a-users-preferred-color-scheme-in-javascript-ec8ee514f1ef

[tom-un]

On macOS Mojave, things works best when using semantic colors: one sets colors on NSView using semantic colors such as [NSColor windowBackgroundColor] etc. Every view in the hierarchy has an 'effectiveAppearance' property that can change when the system changes from light to dark mode or vis versa. When the layers backing the views re-render the conversion of the NSColor to a CGColor is automatically aware of the effectiveAppearance and you'll get a different RGB value in the CGColor. iOS doesn't have appearance changes yet, but its a good bet it will in the same way as Mojave soon -- looking forward to WWDC for more info there.

I prototyped a couple approaches when making our macOS react-native Mojave theme aware. The first approach was to make a JS Api similar to Platform. I called it SemanticColor.js and it behaved similar to Platform: on JS load it used NativeModule constants to initialize a map of semantic color names to RGB string. Then the JS subscribed to an 'theme has changed' event that would be send a new map -- similar to how Platform caches the screen orientation and then gets updated orientation values from an event.

The problem with this solution was that the JS App itself also had to subscribe to the "theme has changed" event and then had to do a hard re-render of the components so that StyleSheets would be reevaluated because the various StyleSheets now contains RGB values fetched from the SematnicColors.js dictionary. Doing such a hard re-render would invariably reset some App state that the App developer didn't bother persisting. A simple example RNTester which does persist which test panel the user has navigated to, and the filter string, but does't persist the scroll position in the list. So with every theme change the list pops back to the top. Also, the time to re-render the whole App can be too slow so that instead of the RN app participating in the nice Mojave theme change animation it would just pop to the new theme a second or two after the rest of the desktop.

So the second approach, which is what is in our macos fork, is the extension to the color type itself, so that a color can be expressed as the current RGB string values or a JSON object like { semantic: 'windowBackground' }. The RCTConvert object turns such JSON objects into a true NSColor semantic color. mac and iOS also have the concept of Asset colors: app defined named colors that have a light and dark variant. I made a RCTDynamic color (a sublcass of NSColor) that works like an Asset color. The JS can express the tuple { dynamic: { light: 'rgb', dark:'rgb' } } and RCTConvert turns it into a RCTDynamic.

The semantic names I came up with for { semantic: 'name' } map 1:1 to the mac NSColor semantic names. And hopefully those same names will be used in a future iOS. But obviously don't map to other platform 1:1. Perhaps we could define a platform agnostic semantic namespace that would serve apple/android/windows.

[DimitarNestorov]

This should continue the conversation: https://developer.apple.com/videos/play/wwdc2019/214/

[kikisaints]

Hey! Poking this thread a bit with some interest on the React Native for Windows side.

I'm a PM on that team (RN for Windows) and we're looking to enable support for the light and dark themes that we have.

With the introduction of Dark theme in iOS 13 - as @DimitarNestorov mentioned, and the Dark theme mode in Android it's probably time we had something like this for all systems.

We have an internal proposal to support both themes, as they're integral to developing on Windows, but I'd like to append that here to get the opinions of the community before we submit a larger spec PR to the main React Native github.

Here's a look at part of the spec I've written that I would like to introduce to React Native core. I actually work closely with @acoates-ms, so a lot of this may look familiar to his suggested approach above as well as similar to what @tom-un was looking at. I would love feedback 😄

Responding to Light/Dark Themes in React Native

Summary

With the introduction of React Native for Windows, there needs to be a way to utilize/work with the Light and Dark themes at the JavaScript layer.

This feature was pitched in the React Native for Windows repo here.

Motivation

Any React Native developer that wishes to follow the guidance of a Windows app will need to have access to the theme brushes, or at the very least a way to know when the system theme has changed.

There are several reasons why this is important to the React Native developer when they run their app on Windows:

• Many native Windows components will honor the Light/Dark theme changes automatically. Giving the app-developer access/knowledge of those changes reduces the "zebra" UI effect (zebra UI = a page in an app where some controls honor a theme system, while others do not, or honor a non-complimentary one)
• Having access to a theme changed event allows a React Native developer to better brand and customize their app for Windows, by accommodating their own styles based on the theme selected by the user (typically set through system settings)
• Exposing the Windows theme up to the JavaScript layer means React Native apps can blend more seamlessly into the Fluent Design system and native Windows platform more easily
• Both Android and iOS 13 have or will have support for Dark themes, thus it is a necessity that we expose some way of detecting and handling theme changes at the RN layer.

Scope

There are two core aspects that need to be available to the app developer in order to have a Windows Light/Dark theme sensitive app:

#	Feature
1	Expose a way, at the JavaScript layer, to detect current theme and when the theme has changed

Basic examples

Example 1 : Set up and behaviors on theme changed

In this example, we'll look at three things:

• How to set up your React Native app to be style and event sensitive to the system themes
• How to switch styles when a theme change has occurred
• Handling a theme changed event

Setting up your app to be sensitive to theme changes

First import the Platform API into your React Native app.

import { AppThemeState } from 'react-native';

Create a local variable to use in style conditionals or to reference elsewhere easily.

class MyAppClass extends Component {
  state = {
    appThemeState: AppThemeState.currentTheme,
  };
  ...
}

Switching styles based on the app's theme

If the app author wants to switch the style of their component manually based on the system's theme (Dark or Light), they can do so with CSS style conditionals.

<TextInput
    style={[styles.inputStyle, this.state.appThemeState.currentTheme == 'dark' ? styles.darkInput : styles.lightInput]}
</TextInput>

Handling a theme changed event

In this case an app author would like to do something or preform some behavior when the app's theme has changed.

Note: AppThemeState will be a subclass of NativeEventEmitter.

componentDidMount() {
  AppThemeState.currentTheme.addListener('themechanged', this.onAppThemeChanged);
}

onAppThemeChanged = (event) => {
  /*Logic on theme changed goes here*/
  this.setState({appThemeState: AppThemeState.currentTheme});
}

API Design Overview

A look at the APIs for the features and scope described above.

AppThemeState.currentTheme

The specifics of the event or API being fired/used.

API	Args	Returns	Discription
currentTheme	none	string	currentTheme returns the state of the system theme that the user or native app has set.

App theme enum

The currentTheme returns one of the following string values:

Property	Type	Description
dark	string	A string value defining that the native app is in Dark theme.
light	string	A string value defining that the native app is in Light theme.

Could potentially need a AppThemeState.isHighContrast to detect when the system has initiated a theme for accessible users.

[DimitarNestorov]

I thought of a bit different approach on the API though. I was thinking about developer experience and the thought of event emitters just scared me.

Let's start with the basics:
useDarkMode - a hook that returns a boolean whether to use dark mode or not.
useDarkModeContext - the hook that every other hook depends on. Returns 'light' or 'dark'.

I borrowed the idea from Apple about dynamic values (UIColor with a callback, 20:50 of the talk). However React Native doesn't use objects or functions for values, so I thought of dynamic stylesheets. Basically our good old StyleSheet with support for dynamic values.

const dynamicStyles = new DynamicStyleSheet({
	container: {
		backgroundColor: new DynamicValue('white', 'black'),
		flex: 1
	},
	text: {
		color: new DynamicValue('black', 'white'),
		textAlign: 'center'
	}
})

function Component() {
	const styles = useDynamicStyleSheet(dynamicStyles)
	
	return (
		<View style={styles.container}>
			<Text style={styles.text}>My text</Text>
		</View>
	)
}

And here's the benefit to such an approach: let's say that this component is being reused inside a view that has to be only in dark mode. No problem, useDynamicStyleSheet will use context underneath so all you'll have to do is provide the theme you want that component to be in:

function MyScreen() {
	return (
		<>
			<DarkModeProvider mode="dark">
				<Component />{/* will be rendered using dark theme */}
			</DarkModeProvider>

			<DarkModeProvider mode="light">
				<Component />{/* will be rendered using light theme */}
			</DarkModeProvider>

			<Component />{/* will be rendered using current theme */}
		</>
	)
}

DynamicValue would be just an object that holds values for each theme. Literally the source code:

export class DynamicValue<T> {
	constructor(public readonly light: T, public readonly dark: T) { }
}

DynamicStyleSheet creates two stylesheet objects for each theme upon construction. useDynamicStyleSheet returns the appropriate stylesheet.

useDynamicValue which just returns the appropriate value from a DynamicValue object or from args (first arg for light theme, second for dark theme).

const logoUri = new DynamicValue(require('./light.png'), require('./dark.png'))
function Logo() {
	const source = useDynamicValue(logoUri)
	return <Image source={source} />
}

function Input() {
	const placeholderColor = useDynamicValue('black', 'white')
	return <TextInput placeholderTextColor={placeholderColor} />
}

---

I got excited last week about dark mode on iOS and I already implemented those ideas: https://github.com/codemotionapps/react-native-dark-mode

These hooks currently work because of a native module, which publishes changes to the theme using event emitter. And if you want to subscribe to that event emitter all you have to do is import it (hopefully you don't).

To detect the theme change in iOS I decided to use method swizzling on UIScreens traitCollectionDidChange and a lot of static methods 😅. This approach can be avoided if theming becomes a part of the React Native core 🙌 (override traitCollectionDidChange on the root React Native view controller).

---

My proposal: A similar high level API, with an alternative for class components. And a better solution for the iOS implementation, something that would require a tiny change to RN core to keep it lean, have it as a module like AsyncStorage and the others.

[tom-un]

@DimitarNestorov : that's a really intriguing proposal. The DynamicValues and DynamicStyleSheet approach has advantages over an event emitter approach. (I prototyped an event emitter approach for macOS dark mode and noted the downsides in my post above). I also feel the semantic color values of the platform are also important. They're important for continuity across the device, but really important for continuity in apps that are hybrids contain a mix of pure native views and react-native views.

I finally made the time to extend the work I did in macOS react-native dark mode to iOS. As expected, the iOS mechanism revealed at WWDC is very similar to macOS. Here's what the prototype looks like:

The branch with the code changes is here: microsoft/react-native-macos@master...tom-un:tomun/ios-darkmode

My proposed change is a change to core: its a change to the ColorType itself to support a platform specific named color. Every platform has some notion of named colors, and adding them to each platform's implementation I believe is a win for the react-native platform. Dimitar's proposal is also really interesting in that it provides a generic dynamic type that is applicable for things beyond just colors, like dynamic image sets.