react-native-tvos
Going forward, Apple TV support for React Native will be maintained here and in the corresponding react-native-tvos
NPM package, and not in the core repo. This is a full fork of the main repository, with only the changes needed to support Apple TV.
Releases of react-native-tvos
will be based on a public release of react-native
; e.g. the 0.60.4-6 release of this package will be derived from the 0.60.4 release of react-native
.
Releases will be published on npmjs.org and you may find the latest release version here: https://www.npmjs.com/package/react-native-tvos?activeTab=versions or use the tag @latest
You will find the relevant tvOS support and maintence within the branches marked tvos
;
To build your project for Apple TV, you should change your package.json
imports to import react-native
as follows, so that this package is used.
"react-native": "npm:react-native-tvos@latest",
General support for Apple TV
TV devices support has been implemented with the intention of making existing React Native applications "just work" on Apple TV, with few or no changes needed in the JavaScript code for the applications.
The RNTester app supports Apple TV.
- Without cocoapods: In
RNTester/RNTester.xcodeproj
, use the RNTester-tvOS
build target to build for tvOS. - With cocoapods: In this repo,
RNTester/Podfile
and RNTester/RNTesterPods.xcodeproj
have been modified to work for tvOS. Run pod install
, then open RNTesterPods.xcworkspace
and build.
Build changes
-
Native layer: React Native Xcode projects all now have Apple TV build targets, with names ending in the string '-tvOS'.
-
react-native init: New React Native projects created with react-native init
will have Apple TV target automatically created in their XCode projects. To use this NPM package for creating a new project, you can reference it as in the following example:
react-native init TestApp --version=react-native@npm:react-native-tvos@latest
cd TestApp && react-native run-ios --simulator "Apple TV" --scheme "TestApp-tvOS"
The workspace will have both iOS and tvOS targets that you can build and run.
- JavaScript layer: Support for Apple TV has been added to
Platform.ios.js
. You can check whether code is running on AppleTV by doing
var Platform = require('Platform');
var running_on_tv = Platform.isTV;
var running_on_apple_tv = Platform.isTVOS;
Code changes
-
General support for tvOS: Apple TV specific changes in native code are all wrapped by the TARGET_OS_TV define. These include changes to suppress APIs that are not supported on tvOS (e.g. web views, sliders, switches, status bar, etc.), and changes to support user input from the TV remote or keyboard.
-
Common codebase: Since tvOS and iOS share most Objective-C and JavaScript code in common, most documentation for iOS applies equally to tvOS.
-
Access to touchable controls: When running on Apple TV, the native view class is RCTTVView
, which has additional methods to make use of the tvOS focus engine. The Touchable
mixin has code added to detect focus changes and use existing methods to style the components properly and initiate the proper actions when the view is selected using the TV remote, so TouchableWithoutFeedback
, TouchableHighlight
and TouchableOpacity
will "just work". In particular:
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 actually selected by pressing the "select" button on the TV remote.
-
TV remote/keyboard input: A new native class, RCTTVRemoteHandler
, sets up gesture recognizers for TV remote events. When TV remote events occur, this class fires notifications that are picked up by RCTTVNavigationEventEmitter
(a subclass of RCTEventEmitter
), that fires a JS event. This event will be picked up by instances of the TVEventHandler
JavaScript object. Application code that needs to implement custom handling of TV remote events can create an instance of TVEventHandler
and listen for these events, as in the following code:
var TVEventHandler = require('TVEventHandler');
class Game2048 extends React.Component {
_tvEventHandler: any;
_enableTVEventHandler() {
this._tvEventHandler = new TVEventHandler();
this._tvEventHandler.enable(this, function(cmp, evt) {
if (evt && evt.eventType === 'right') {
cmp.setState({board: cmp.state.board.move(2)});
} else if(evt && evt.eventType === 'up') {
cmp.setState({board: cmp.state.board.move(1)});
} else if(evt && evt.eventType === 'left') {
cmp.setState({board: cmp.state.board.move(0)});
} else if(evt && evt.eventType === 'down') {
cmp.setState({board: cmp.state.board.move(3)});
} else if(evt && evt.eventType === 'playPause') {
cmp.restartGame();
}
});
}
_disableTVEventHandler() {
if (this._tvEventHandler) {
this._tvEventHandler.disable();
delete this._tvEventHandler;
}
}
componentDidMount() {
this._enableTVEventHandler();
}
componentWillUnmount() {
this._disableTVEventHandler();
}
-
Turbomodules: Working as of the 0.60.4-0 release.
-
Dev Menu support: On the simulator, cmd-D will bring up the developer menu, just like on iOS. To bring it up on a real Apple TV device, make a long press on the play/pause button on the remote. (Please do not shake the Apple TV device, that will not work :) )
-
TV remote animations: RCTTVView
native code implements Apple-recommended parallax animations to help guide the eye as the user navigates through views. The animations can be disabled or adjusted with new optional view properties.
-
Back navigation with the TV remote menu button: The BackHandler
component, originally written to support the Android back button, now also supports back navigation on the Apple TV using the menu button on the TV remote.
-
TabBarIOS behavior: The TabBarIOS
component wraps the native UITabBar
API, which works differently on Apple TV. To avoid jittery rerendering of the tab bar in tvOS (see this issue), the selected tab bar item can only be set from Javascript on initial render, and is controlled after that by the user through native code.
-
TVMenuControl: This module provides methods to enable and disable navigation using the menu key on the TV remote. This is required in order to fix an issue with Apple's guidelines for menu key navigation (see https://github.com/facebook/react-native/issues/18930). The RNTester
app uses this new module to implement correct menu key behavior.
-
TVFocusGuideView: This component provides support for Apple's UIFocusGuide
API, to help ensure that focusable controls can be navigated to, even if they are not directly in line with other controls. A new example is provided in RNTester
.
-
Known issues:
- As of the 0.60.4-0 release, Fabric code compiles. Does not yet run in RNTester (Yoga errors) -- the issue is under investigation.