React Native for TV: Android TV and tvOS Navigation

1. react-native-tvos: the foundation for TV apps built with React Native

React Native does not support TV platforms through the official core repository but through react-native-tvos, a fork actively maintained by the community that ships extra native modules and adjustments for Android TV and tvOS, while the JavaScript API stays largely identical to standard React Native. This fork gets deliberately published as its own npm package and kept regularly in sync with new React Native releases, so an existing mobile project can, in many cases, get extended with a separate TV target with manageable effort, without duplicating the entire codebase.

The practical starting point is usually a separate Expo preset or a dedicated native configuration that exists alongside the existing mobile configuration, because TV apps need their own native project files, such as an extra Android TV manifest or a dedicated tvOS Xcode target. A shared JavaScript code portion survives this through platform switches such as Platform.isTV, while platform specific native setup gets maintained separately.

2. Focus management as the central control concept

Unlike touch surfaces, where every element can be touched directly and independently, a television has exactly one focused element at any given time, steered through the remote's directional buttons and triggered through a select button. This focus model requires every interactive component to be explicitly focusable, and requires the order in which focus moves between elements to stay predictable and logically traceable, rather than resulting randomly from visual arrangement alone.

The TVFocusGuideView component from react-native-tvos takes on the job of deliberately steering focus within a given area, for example ensuring focus automatically jumps to a sensible starting element the first time a screen is entered, instead of landing on an arbitrary, possibly invisible element. For individual elements, the hasTVPreferredFocus prop additionally lets you specify explicitly which element should receive initial focus when a screen renders.

import { TVFocusGuideView } from 'react-native';

function ProductGrid({ products }: { products: Product[] }) {
  return (
    <TVFocusGuideView autoFocus style={{ flexDirection: 'row', flexWrap: 'wrap' }}>
      {products.map((product, index) => (
        <ProductTile
          key={product.id}
          product={product}
          hasTVPreferredFocus={index === 0}
        />
      ))}
    </TVFocusGuideView>
  );
}

3. Capturing remote control events with TVEventHandler

TVEventHandler lets you capture remote control events, such as pressing the back button, triggering the menu button on the Apple TV Remote, or play and pause buttons, directly in JavaScript, regardless of which element currently holds focus. This mechanism suits global actions in particular, such as closing a video player through the back button or showing a context menu on a long press, actions that cannot sensibly be tied to a single focusable element.

For most everyday interactions, such as selecting a menu item or starting a video, the regular onPress handler of a Pressable component is sufficient instead, because the operating system automatically interprets the remote's select button as a press event on the currently focused element. TVEventHandler therefore stays limited to edge cases outside the normal focus interaction model and should not be mistaken for a general alternative to the focus system.

4. Adapting existing touch components for focus

A Pressable component designed for touch typically only reacts to onPress and perhaps onPressIn and onPressOut, but has no visual feedback for a focus state at all, because that state simply does not exist on a touch surface. For TV platforms, the same component must additionally react to onFocus and onBlur while showing a clearly recognizable visual difference, such as scaling, a border or a shadow, because without that visual cue users on a television simply cannot tell which element is currently interactable.

In practice, a shared FocusablePressable wrapper component pays off, one that behaves like a normal Pressable on mobile platforms and additionally manages local focus state through useState on TV platforms, driving scale and border color through the Animated API based on that state. This encapsulation prevents focus logic from having to be implemented separately in every single component throughout the app.

import { useState } from 'react';
import { Pressable, Animated, Platform } from 'react-native';

function FocusablePressable({ onPress, children }: Props) {
  const [focused, setFocused] = useState(false);

  return (
    <Pressable
      onPress={onPress}
      onFocus={() => setFocused(true)}
      onBlur={() => setFocused(false)}
      style={[
        styles.base,
        Platform.isTV && focused ? styles.focused : null,
      ]}
    >
      {children}
    </Pressable>
  );
}

5. Android TV: specifics and store requirements

Android TV requires a dedicated banner image in AndroidManifest.xml for publishing on television devices through the Google Play Store, along with an explicit declaration of the app as leanback capable through the android.software.leanback feature, because the Leanback launcher, Android's tile based TV home screen, simply will not list the app in its overview without these declarations. The app must also explicitly declare that it does not require a touchscreen, since the Play Store otherwise assumes a phone or tablet target device by default and the app stays invisible on Android TV devices.

On a technical level, Android TV's focus behavior additionally differs by relying heavily on the native Android view focus system, which lets individual focus order adjustments be made through nextFocusUp, nextFocusDown, nextFocusLeft and nextFocusRight, useful when the system's automatic, geometrically determined focus order does not produce the desired result in a specific layout, for example with asymmetrically arranged card grids.

6. tvOS: the Focus Engine, Siri Remote and parallax

Apple's tvOS manages focus through its own Focus Engine, which, unlike Android's explicit nextFocus system, automatically decides based on the geometric arrangement of visible elements which element gets focused next on a directional button press, without developers needing to manually define that order in most cases. This automatic determination works reliably for regular grid layouts, but can lead to unexpected jumps with irregularly positioned or overlapping elements, fixable only through deliberate layout restructuring or through TVFocusGuideView.

The Siri Remote additionally differs from classic remote controls through its touch pad, which detects swipe gestures instead of classic directional buttons, something React Native maps through the same focus movement events, so no difference shows up at the JavaScript level compared to the older, button based Siri Remote. tvOS also commonly expects a subtle parallax effect on focused image elements, configurable on Image elements through a native tvOS component such as TVParallaxProperties, matching the native look of typical tvOS apps.

7. Navigation patterns for TV: grid instead of list, focus instead of touch

React Navigation generally works on TV platforms too, but with one important conceptual shift: where a mobile app often relies on long, vertically scrollable lists, horizontally and vertically navigable grid layouts dominate on television, because that structure matches the remote's four directional movement more naturally than a purely vertical list does. A tab navigation along the top of the screen often replaces the bottom tab bar familiar from mobile, since the bottom edge of the screen sits outside comfortable viewing range on large televisions.

For detail screens, typically implemented on mobile as push navigation inside a stack, the same stack concept remains technically functional on TV platforms but should work with larger, clearly recognizable focus targets, since small touch targets that work well on a phone display are barely recognizable from several meters away on a television. A proven rule of thumb sizes focusable elements at least twice as large visually as comparable mobile elements.

8. Testing on Android TV emulators and tvOS simulators

The Android Studio Device Manager offers dedicated Android TV emulator profiles at various resolutions, controlled through the computer keyboard's arrow keys, which is fully sufficient for initial functional tests of focus navigation but does not fully substitute for genuine usability with a real remote from a typical living room distance. The tvOS Simulator in Xcode offers comparable behavior and can additionally be controlled through a simulated Siri Remote including touch pad swipe gestures.

For a realistic final acceptance check, every TV app should additionally be tested on at least one physical device per platform, since both the actual input latency of the remote and the real legibility of text and focus indicators from typical couch viewing distance can only be judged to a limited extent in an emulator. Minimum font size and the contrast of focus rings in particular should get verified on a real television from several meters away.

9. Common pitfalls: missing focus indicators and scroll synchronization

The most common mistake when porting an existing mobile app to TV is a missing or overly subtle visual focus indicator, because a component designed for touch often defines no visible difference at all between a focused and an unfocused state. Without that indicator, an app on a television feels effectively unusable to users, even if the underlying navigation works correctly on a technical level, because nobody can tell which element the select button would currently trigger.

A second, subtler problem shows up when a ScrollView or FlatList correctly moves focus between its elements but does not automatically scroll along with it, leaving a focused element at the bottom of the screen partially or fully invisible. This gets fixed by triggering scrollToIndex, or a comparable call, specifically on each list item's onFocus, actively pulling the focused element back into the visible area instead of relying on automatic scroll behavior, which works less reliably on TV platforms than on mobile.

10. Summary

11. FAQ: React Native for TV: Key Takeaways