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.
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
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
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:
react-native run-ios --simulator "Apple TV" --scheme "TestApp-tvOS"
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
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:
onFocuswill be executed when the touchable view goes into focus
onBlurwill be executed when the touchable view goes out of focus
onPresswill 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.