Registry / web-framework / react-native-tvos

react-native-tvos

library0.85.0-0jsnpmunverified

This package provides a fork of React Native specifically adapted for developing applications on TV platforms, including Apple TV (tvOS) and Android TV. It extends the core React Native framework with TV-specific navigation primitives, focus management, and input handling necessary for an optimal 10-foot user experience. The current stable version, `0.85.0-0`, aligns closely with mainstream React Native releases (e.g., React Native 0.85.x) but maintains its own maintenance cycle to integrate TV-specific features and fixes. Development appears active, with frequent updates tracking React Native's primary release train, evidenced by recent `0.85.0-0` release candidates and the final `0.85.0-0` release following `0.84.x` and `0.83.x`. Its key differentiators lie in its specialized focus engine, robust remote control input integration, and UI component adaptations for large screen environments, making it the primary choice for building native TV applications with React.

web-framework http-networking

npm install react-native-tvos

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-NATIVE-TVOS

react-native-tvos

web-frameworkjavascriptv0.85.0-0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

View, Text, StyleSheet

✓ import { View, Text, StyleSheet } from 'react-native-tvos';

✗ const { View, Text, StyleSheet } = require('react-native-tvos');

Core React Native components are re-exported by `react-native-tvos`. It's crucial to ensure your `package.json` aliases `react-native` to `react-native-tvos` to correctly use these components within a TV project (`"react-native": "npm:react-native-tvos@latest"`).

TouchableOpacity

✓ import { TouchableOpacity } from 'react-native-tvos';

Interactive components like `TouchableOpacity` are adapted for TV focus and remote input within the `react-native-tvos` fork. They gain focus-specific styling and event handling automatically.

TVEventHandler

✓ import { TVEventHandler } from 'react-native-tvos';

The `TVEventHandler` module provides direct access to raw remote control events, useful for custom input handling beyond standard focusable components. For functional components, the `useTVEventHandler` hook is often preferred.

TVFocusGuideView

✓ import { TVFocusGuideView } from 'react-native-tvos';

`TVFocusGuideView` is a critical component for managing complex focus navigation patterns, especially when native focus engines (proximity-based on Android TV, precision-based on tvOS) behave unexpectedly. It helps define explicit focus paths.

Demonstrates a basic React Native for TV application with focusable elements, remote control input handling using `TVEventHandler`, and dynamic style changes based on focus state. This provides a foundational example for building interactive TV user interfaces.

import React, { useState, useEffect } from 'react'; import { View, Text, StyleSheet, TouchableOpacity, TVEventHandler } from 'react-native-tvos'; const App = () => { const [focusedItem, setFocusedItem] = useState('none'); useEffect(() => { const tvEventHandler = new TVEventHandler(); tvEventHandler.enable(this, (cmp, evt) => { if (evt && evt.eventKind === 'select') { console.log(`Item selected: ${focusedItem}`); // Handle selection logic based on focusedItem } }); return () => { tvEventHandler.disable(); }; }, [focusedItem]); return ( <View style={styles.container}> <Text style={styles.header}>Welcome to React Native TV!</Text> <TouchableOpacity onFocus={() => setFocusedItem('Button 1')} onBlur={() => setFocusedItem('none')} style={[styles.button, focusedItem === 'Button 1' && styles.buttonFocused]} activeOpacity={0.8} testID="button1" > <Text style={styles.buttonText}>Button 1</Text> </TouchableOpacity> <TouchableOpacity onFocus={() => setFocusedItem('Button 2')} onBlur={() => setFocusedItem('none')} style={[styles.button, focusedItem === 'Button 2' && styles.buttonFocused]} activeOpacity={0.8} testID="button2" > <Text style={styles.buttonText}>Button 2</Text> </TouchableOpacity> <Text style={styles.footer}>Currently focused: {focusedItem}</Text> </View> ); }; const styles = StyleSheet.create({ container: { flex: 1, justifyContent: 'center', alignItems: 'center', backgroundColor: '#222', }, header: { fontSize: 48, color: 'white', marginBottom: 40, }, button: { backgroundColor: '#4CAF50', paddingVertical: 20, paddingHorizontal: 50, borderRadius: 10, marginVertical: 15, width: 400, alignItems: 'center', }, buttonFocused: { borderColor: 'yellow', borderWidth: 5, }, buttonText: { color: 'white', fontSize: 32, fontWeight: 'bold', }, footer: { fontSize: 28, color: '#AAA', marginTop: 40, }, }); export default App;

Debug

Known issues

breakingA regression was introduced in `disabled=true` behavior on Android TV (issue #1058), potentially causing UI elements with this prop to not behave as expected or still receive focus/interaction.

fix

Review affected components. If possible, upgrade to a patched version once available, or implement custom logic to prevent interaction for disabled elements.

affects: 0.84.0-0

breakingNode.js engine requirements have become stricter with recent releases. Using an unsupported Node.js version (e.g., below v20.19.4 for current versions) can lead to build failures or unexpected runtime errors during development.

fix

Ensure your Node.js version matches the specified engine requirements (`^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0`). Use `nvm` or a similar tool to manage Node.js versions.

affects: >=0.85.0-0

gotchaFocus management is critical for TV applications. Overriding default focus behavior or not handling focusable elements correctly can lead to a poor user experience, especially with remote control navigation.

fix

Utilize `focusable`, `nextFocusDown`, `nextFocusUp`, etc., props and ensure all interactive elements are properly focusable. Test extensively with a remote control simulator or physical device. Consider `TVFocusGuideView` for complex layouts.

affects: >=0.60.0

gotchaWhile based on React Native, `react-native-tvos` includes specific adaptations. Direct usage of some web-oriented components or third-party libraries without TV-specific considerations might lead to unexpected behavior or require manual adjustments for focus and input.

fix

Prioritize `react-native-tvos` components and modules. For third-party libraries, verify TV compatibility or implement wrappers to adapt them for TV input and focus paradigms.

affects: >=0.60.0

deprecatedOlder versions of React Native for TV might use deprecated APIs or have different behaviors regarding event handlers (e.g., older `TVEventHandler` patterns). Ensure you are using the latest recommended patterns for remote input.

fix

Consult the official `react-native-tvos` documentation and upgrade to recent versions to leverage improved input handling and focus management systems. Refactor legacy `TVEventHandler` implementations if necessary, possibly using the `useTVEventHandler` hook.

affects: <0.80.0

gotchaUpgrading `react-native-tvos` often involves a corresponding upgrade of the core React Native dependency, which can introduce breaking changes from the upstream project. Manual linking or specific Xcode/Android Studio steps might be required.

fix

Always review the upgrade guide for both `react-native-tvos` and the corresponding upstream React Native version. Expect manual intervention for native project files (e.g., `Podfile`, `build.gradle`). Use `npx react-native upgrade` as a starting point but be prepared for conflicts.

affects: >=0.60.0

Errors

Common errors & fixes

Error: Command 'run-ios' unrecognized. Did you mean run-android, run-ios, run-windows?

Attempting to run `react-native run-ios` for a tvOS project without specifying the correct scheme or destination for Apple TV.

fix

Use `npx react-native run-ios --scheme <YourApp>-tvOS --destination 'platform=tvOS Simulator,name=Apple TV'` or similar. Ensure your Xcode project has a tvOS scheme configured and that `react-native-tvos` is properly integrated.

Invariant Violation: View config not found for name ReactNativeARTGroup. Make sure to start with 'RCT' or 'RK'

Missing native module linkage or an issue with the native build configuration, often after an upgrade or adding a new native library. This specific error often relates to legacy drawing libraries.

fix

For iOS/tvOS, navigate to the `ios` directory and run `pod install`. For Android, run `gradlew clean` and rebuild the project. Confirm that `react-native-tvos` native modules are correctly linked and that autolinking is working.

TypeError: Cannot read property 'View' of undefined. (or similar for other core components)

This typically occurs when `react-native-tvos` is not correctly aliased to `react-native` in `package.json`, causing the bundler to try and load core `react-native` which lacks TV-specific exports or expects a different native setup.

fix

Add or update your `package.json` to include `"resolutions": { "react-native": "npm:react-native-tvos@latest" }` (for Yarn) or `"overrides": { "react-native": "npm:react-native-tvos@latest" }` (for npm 8+) to alias the package properly. Then, reinstall dependencies (`yarn install` or `npm install`).

Cannot find name 'React'. Did you mean 'react'?

Incorrect `React` import in a TypeScript file or missing `@types/react`.

fix

Ensure you have `import React from 'react';` at the top of your `.tsx` or `.jsx` files and that `@types/react` is installed as a dev dependency (`npm install --save-dev @types/react`).

Focus does not return to the initial element after re-applying `hasTVPreferredFocus: true`

A known issue in certain versions where `setNativeProps({ hasTVPreferredFocus: true })` does not reliably re-apply focus after an element has lost and regained focus once.

fix

This is a regression in specific versions. Consider upgrading to a patched version if available. Workarounds might involve manually managing focus state or using `TVFocusGuideView` to explicitly guide focus.

Upgrade

Version history

0.85.0-0latest on npm

Audit

Dependencies

reactrequiredCore React library for UI component declarations.

@types/reactoptionalTypeScript type definitions for React, recommended for TypeScript projects.

@react-native/jest-presetoptionalJest configuration preset for testing React Native projects.

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/react-native-tvos/react-native-tvos ↗

packagehttps://www.npmjs.com/package/react-native-tvos ↗

homepagehttps://react-native-tv.github.io/react-native-tvos/ ↗