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.]

If we were creating a new app using the React Native core package, we would then do

Instead, to get support for TV, we do this:

As with React Native core, we can run the app on an iOS phone simulator:

But now, we have the option of running on Apple TV simulator:

For Android, the command is similar:

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 focus
  • onBlur will be executed when the touchable view goes out of focus
  • onPress 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.

Now, when we run the app, we will see a small display in the top right corner that updates each time the user does an action with the remote.

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.

Software Architect at Salesforce. Creator of the React Native Apple TV port.