React Native on the Big Screen — Part 1: Introduction
The React Native framework, used to build mobile applications for iOS and Android, is not just for phone apps anymore.
For example, the react-native-windows project (supported by Microsoft) enables development of React applications that run natively on Windows 10 and Mac OS. The react-native-web project makes it possible to run React Native components and APIs on the web using React DOM.
It is also possible to build React Native apps that work on TV platforms (Apple TV and Android TV). Depending on the components being used, the same application code can run on phones and TVs with very few changes needed.
Support for TV platforms is found in the react-native-tvos repository and corresponding NPM package. This is a full fork of the core React Native repository, and retains all of the core repository’s support for iOS and Android phone apps.
This article will go through the first steps to show how we can create a React Native starter app for TV, and show how to detect events coming from the TV remote control.
Getting started
Starting a new project for TV with react-native-tvos
is easy — it uses the same CLI and the same steps as for iOS/Android. The new project will work for iOS and Android phone apps as well as Apple TV and Android TV apps.
First, we make sure that the new community React Native CLI is installed on our development machine (this step only needs to be done once). [The older CLI can also be used — instructions can be found in the react-native-tvos
README.]
npm install -g @react-native-community/cli
If we were creating a new app using the React Native core package, we would then do
react-native init TestApp
Instead, to get support for TV, we do this:
react-native init TestApp --template=react-native-tvos
# The template can also be
# react-native-tvos@latest
# react-native-tvos@0.63.1-1
# etc.
As with React Native core, we can run the app on an iOS phone simulator:
cd TestApp
react-native run-ios
But now, we have the option of running on Apple TV simulator:
react-native run-ios --simulator "Apple TV" --scheme "TestApp-tvOS"
For Android, the command is similar:
react-native run-android
The app will run on whichever Android emulator we have running, which can be either a phone emulator or Android TV emulator.
Handling input using the TV remote
In general, TVs do not have touchscreens. The user interacts with the TV using a remote control (Siri remote for Apple TV, or a directional pad for Android TV). Controls that would be buttons or touchables on a mobile device are now focusable controls. Based on input from the arrow keys, or swipes of the Siri remote touchpad, a focus engine inside the OS decides which control will receive focus next. When the user clicks the remote control (or presses return on a keyboard or keypad), the control is activated in the same way that a press on a touchscreen would on a mobile device.
The React Native TV code is designed so that TouchableHighlight
and TouchableOpacity
work exactly as we would expect, and can be focused by the focus engine. When one of these controls is focused, it gets the same highlight or opacity change that it would during a press on a mobile device. Notice that in the Apple TV screen shot above, the first row in the list of “Learn More” links is dimmed. This is a TouchableOpacity
and is the topmost control on the screen, and is therefore focused by default when the app renders. When focused, a TouchableOpacity
dims, in the same way that it dims temporarily when pressed on a mobile device.
There are also props provided to enable the developer to change state or perform other actions during these transitions:
onFocus
will be executed when the touchable view goes into focusonBlur
will be executed when the touchable view goes out of focusonPress
will be executed when the touchable view is focused and the user presses the "select" or center button on the TV remote (same as pressing the touchable on a mobile device)
The developer may also implement their own code to explicitly listen for events coming from the TV remote and respond to them. This is done using the TVEventHandler
module, and optionally the useTVEventHandler
hook for functional components.
To demonstrate this, let’s modify the new project created above so that it imports useTVEventHandler
and detects the events being sent by the remote control to display them in the UI.
The next article in this series will go into detail on some of the other new React Native APIs and components that are available for TV apps, and also discuss some of the other important differences between TV and mobile apps.