{"id":11806,"library":"react-native-tvos","title":"React Native for TV","description":"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.","status":"active","version":"0.85.0-0","language":"javascript","source_language":"en","source_url":"https://github.com/react-native-tvos/react-native-tvos","tags":["javascript","react","react-native","android","ios","tvos","apple tv","android tv","mobile","typescript"],"install":[{"cmd":"npm install react-native-tvos","lang":"bash","label":"npm"},{"cmd":"yarn add react-native-tvos","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-native-tvos","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core React library for UI component declarations.","package":"react","optional":false},{"reason":"TypeScript type definitions for React, recommended for TypeScript projects.","package":"@types/react","optional":true},{"reason":"Jest configuration preset for testing React Native projects.","package":"@react-native/jest-preset","optional":true}],"imports":[{"note":"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\"`).","wrong":"const { View, Text, StyleSheet } = require('react-native-tvos');","symbol":"View, Text, StyleSheet","correct":"import { View, Text, StyleSheet } from 'react-native-tvos';"},{"note":"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.","symbol":"TouchableOpacity","correct":"import { TouchableOpacity } from 'react-native-tvos';"},{"note":"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.","symbol":"TVEventHandler","correct":"import { TVEventHandler } from 'react-native-tvos';"},{"note":"`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.","symbol":"TVFocusGuideView","correct":"import { TVFocusGuideView } from 'react-native-tvos';"}],"quickstart":{"code":"import React, { useState, useEffect } from 'react';\nimport { View, Text, StyleSheet, TouchableOpacity, TVEventHandler } from 'react-native-tvos';\n\nconst App = () => {\n  const [focusedItem, setFocusedItem] = useState('none');\n\n  useEffect(() => {\n    const tvEventHandler = new TVEventHandler();\n    tvEventHandler.enable(this, (cmp, evt) => {\n      if (evt && evt.eventKind === 'select') {\n        console.log(`Item selected: ${focusedItem}`);\n        // Handle selection logic based on focusedItem\n      }\n    });\n\n    return () => {\n      tvEventHandler.disable();\n    };\n  }, [focusedItem]);\n\n  return (\n    <View style={styles.container}>\n      <Text style={styles.header}>Welcome to React Native TV!</Text>\n      <TouchableOpacity\n        onFocus={() => setFocusedItem('Button 1')}\n        onBlur={() => setFocusedItem('none')}\n        style={[styles.button, focusedItem === 'Button 1' && styles.buttonFocused]}\n        activeOpacity={0.8}\n        testID=\"button1\"\n      >\n        <Text style={styles.buttonText}>Button 1</Text>\n      </TouchableOpacity>\n      <TouchableOpacity\n        onFocus={() => setFocusedItem('Button 2')}\n        onBlur={() => setFocusedItem('none')}\n        style={[styles.button, focusedItem === 'Button 2' && styles.buttonFocused]}\n        activeOpacity={0.8}\n        testID=\"button2\"\n      >\n        <Text style={styles.buttonText}>Button 2</Text>\n      </TouchableOpacity>\n      <Text style={styles.footer}>Currently focused: {focusedItem}</Text>\n    </View>\n  );\n};\n\nconst styles = StyleSheet.create({\n  container: {\n    flex: 1,\n    justifyContent: 'center',\n    alignItems: 'center',\n    backgroundColor: '#222',\n  },\n  header: {\n    fontSize: 48,\n    color: 'white',\n    marginBottom: 40,\n  },\n  button: {\n    backgroundColor: '#4CAF50',\n    paddingVertical: 20,\n    paddingHorizontal: 50,\n    borderRadius: 10,\n    marginVertical: 15,\n    width: 400,\n    alignItems: 'center',\n  },\n  buttonFocused: {\n    borderColor: 'yellow',\n    borderWidth: 5,\n  },\n  buttonText: {\n    color: 'white',\n    fontSize: 32,\n    fontWeight: 'bold',\n  },\n  footer: {\n    fontSize: 28,\n    color: '#AAA',\n    marginTop: 40,\n  },\n});\n\nexport default App;\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Review affected components. If possible, upgrade to a patched version once available, or implement custom logic to prevent interaction for disabled elements.","message":"A 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.","severity":"breaking","affected_versions":"0.84.0-0"},{"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.","message":"Node.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.","severity":"breaking","affected_versions":">=0.85.0-0"},{"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.","message":"Focus 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.","severity":"gotcha","affected_versions":">=0.60.0"},{"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.","message":"While 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.","severity":"gotcha","affected_versions":">=0.60.0"},{"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.","message":"Older 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.","severity":"deprecated","affected_versions":"<0.80.0"},{"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.","message":"Upgrading `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.","severity":"gotcha","affected_versions":">=0.60.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to run `react-native run-ios` for a tvOS project without specifying the correct scheme or destination for Apple TV.","error":"Error: Command 'run-ios' unrecognized. Did you mean run-android, run-ios, run-windows?"},{"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.","cause":"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.","error":"Invariant Violation: View config not found for name ReactNativeARTGroup. Make sure to start with 'RCT' or 'RK'"},{"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`).","cause":"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.","error":"TypeError: Cannot read property 'View' of undefined. (or similar for other core components)"},{"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`).","cause":"Incorrect `React` import in a TypeScript file or missing `@types/react`.","error":"Cannot find name 'React'. Did you mean 'react'?"},{"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.","cause":"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.","error":"Focus does not return to the initial element after re-applying `hasTVPreferredFocus: true`"}],"ecosystem":"npm"}