React Native Tv Best Practices
CallstackOfficialPublished by Callstack
- Skill
- Guidelines
- Software development
- MIT
- No issues found
AutoGineer summary
Written by AutoGineer from the skill’s own files, not by the author
This skill provides a comprehensive set of best practices for building, testing, and debugging React Native applications on TV platforms, including Apple TV, Android TV, Fire TV, and web-based targets. It focuses on the unique challenges of the 10-foot UI, such as remote-based D-pad navigation, focus management, TV-specific performance constraints, and accessibility requirements. The guidance helps developers navigate the differences between various TV stacks like react-native-tvos and Amazon Vega/Kepler.
What it does
- Provides heuristics for 10-foot UI design, typography, and layout.
- Offers strategies for managing focus engines and D-pad navigation.
- Details performance optimization for low-memory TV hardware.
- Outlines requirements for TV-specific accessibility and screen reader support.
- Explains how to handle video playback, DRM, and player controls.
- Guides developers on identifying and setting up the correct TV platform stack.
When to use it
- When building or debugging navigation issues related to remote inputs.
- When optimizing app performance for low-memory TV devices.
- When implementing accessibility features for TV screen readers.
- When troubleshooting video playback or DRM integration errors.
- When designing layouts for 10-foot viewing distances.
Advantages
- Reduces platform-specific bugs by providing clear stack-detection rules.
- Improves user experience through consistent focus and navigation patterns.
- Helps meet accessibility standards required for TV app store approval.
- Provides actionable debugging paths for common TV-specific failures.
Usage examples
- “How do I fix focus jumping to the wrong element in my React Native TV app?”
- The agent will guide you to use focus-management.md, recommending the use of TVFocusGuideView for shared focus paths and advising against imperative focus overrides.
- “My app crashes on Fire TV when scrolling through a long list of posters. What should I check?”
- The agent will point you to perf-lists.md and perf-memory.md to implement proper virtualization and optimize image memory usage for low-memory hardware.
Install
Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/callstackincubator/react-native-tv-best-practices/downloadUnzip it into the cross-client skills folder of your project:
mkdir -p .agents/skills && unzip react-native-tv-best-practices.zip -d .agents/skills
Documentation by Callstack
React Native TV Best Practices
Overview
TV-specific review guidance for React Native-backed apps on Apple TV, Android TV, Fire TV, Amazon Vega/Kepler, and web-based TV targets such as Tizen or webOS.
Use this skill only for TV deltas: remote input, focus engines, 10-foot layout, platform packaging, playback/DRM, low-memory TV hardware, and TV accessibility. For ordinary React Native performance or architecture issues, use react-native-best-practices.
Skill Format
Reference files are grouped by topic prefix:
focus-*: focus engines, focus guides, focus event performancenav-*: D-pad navigation, Back/Menu behavior, keyboard/search inputdesign-*: 10-foot typography, layout, color, focus visibilityperf-*: startup, memory, lists, animation, and network constraints on TV hardwarevideo-*: playback architecture, DRM/protocol selection, debugginga11y-*: TV accessibility implementation and audit checkssetup-*: stack detection, setup, architecture, cross-platform behaviortest-*andrelease-*: test coverage, E2E, and CI/release workflows
When to Apply
Apply this skill when the app targets a TV platform and the work involves:
Focus movement, visible focus, focus restoration, or remote/D-pad input
TV layout readability, overscan/safe areas, or 10-foot UI density
TV player controls, manifests, DRM, decoder support, or playback errors
Performance on low-memory TV hardware, especially with video or large carousels
TV accessibility with screen readers, captions, focus order, or remote-only interaction
Platform setup for
react-native-tvos, Expo TV, Amazon Vega/Kepler, Tizen, or webOS
Before You Start — Identify the TV Stack
This skill covers several TV stacks. Detect which one the app targets before flagging setup issues — demanding react-native-tvos, a tvOS Podfile, or an Android TV manifest on a Vega/Kepler or web-based TV app produces false positives.
| Stack | How to detect | Setup expectations |
|---|---|---|
| react-native-tvos (Apple TV, Android TV, Fire TV) | "react-native": "npm:react-native-tvos@…" in package.json | tvOS Podfile (platform :tvos); Android TV leanback/LEANBACK_LAUNCHER manifest entries; TV emulator/simulator |
| Expo + react-native-tvos | above plus @react-native-tvos/config-tv in app.json | EXPO_TV=1 prebuild; react-native-tvos version must match the Expo SDK; not all Expo features/libraries are available on TV |
| Amazon Vega / Kepler | Vega/Kepler SDK & tooling (@amazon-devices/* deps, Kepler manifest); no react-native-tvos | Amazon's Vega/Kepler toolchain — react-native-tvos, tvOS Podfile, and Android TV manifest do not apply |
| Web-based TV (Tizen, webOS) | web bundler (Rsbuild/webpack) + platform packaging; spatial-nav library | Platform SDK packaging; @noriginmedia/norigin-spatial-navigation for focus |
The focus, 10-foot design, performance, accessibility, and player guidance applies across all of these — only the setup/build expectations are stack-specific.
Review Rules
Resolve the target stack before setup advice.
Prefer natural focus order and focus guides before imperative focus calls or broad
nextFocus*maps.Treat focus loss, invisible focus, and broken Back/Menu behavior as navigation bugs.
Check readability, safe areas, and focus states at TV distance before tuning visual details.
Profile on the weakest supported TV device before reporting performance fixes as complete.
Separate playback failures by layer: manifest request, DRM license exchange, decoder capability, player state, and React UI controls.
Priority-Ordered Guidelines
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Focus and D-pad navigation | CRITICAL | focus-*, nav-* |
| 2 | List, animation, and input performance | CRITICAL | perf-* |
| 3 | Playback and DRM failures | HIGH | video-* |
| 4 | 10-foot readability and layout | HIGH | design-* |
| 5 | TV accessibility | HIGH | a11y-* |
| 6 | Stack setup, testing, and release | MEDIUM | setup-*, test-*, release-* |
Quick Reference
Detect the TV stack from package files, manifests, native folders, and platform tooling.
Reproduce navigation with the remote or D-pad path, not mouse/touch assumptions.
Confirm the focused element is always visible, reachable, and restored after modals/routes.
Check playback failures from the network/DRM layer upward before changing React controls.
Measure list, animation, memory, and startup work on the weakest supported TV target.
References
Focus and Navigation
| File | Impact | Description |
|---|---|---|
| focus-management.md | CRITICAL | Focus engines, focus guides, nextFocus*, and focus restoration |
| focus-performance.md | CRITICAL | Avoiding frame drops from focus event handling |
| nav-directional.md | CRITICAL | Directional navigation rules across TV platforms |
| nav-patterns.md | CRITICAL | Global/local navigation, modals, tabs, and Back behavior |
| nav-keyboard.md | MEDIUM | Search and text input with remotes |
Design
| File | Impact | Description |
|---|---|---|
| design-10foot.md | HIGH | 10-foot review heuristics |
| design-typography.md | HIGH | TV type sizing and readability |
| design-layout.md | HIGH | Safe areas, spacing, carousels, and focus room |
| design-color.md | MEDIUM | Contrast and TV display color constraints |
Performance
| File | Impact | Description |
|---|---|---|
| perf-overview.md | HIGH | TV performance targets and profiling order |
| perf-lists.md | CRITICAL | Virtualized rows and poster-heavy lists |
| perf-animations.md | CRITICAL | Focus and transition animation performance |
| perf-memory.md | HIGH | Low-memory TV crashes and image/video pressure |
| perf-network.md | HIGH | Remote input, request stalls, and network resilience |
Video, Accessibility, Setup, Testing
| File | Impact | Description |
|---|---|---|
| video-streaming.md | HIGH | TV platform protocol/DRM selection |
| video-players.md | HIGH | Player choices and custom controls |
| video-debugging.md | HIGH | Manifest, DRM, codec, and playback debugging |
| a11y-overview.md | MEDIUM | TV-specific accessibility differences |
| a11y-implementation.md | HIGH | Accessible labels, roles, live regions, and focus |
| a11y-checklist.md | MEDIUM | Launch accessibility audit checklist |
| setup-getting-started.md | MEDIUM | react-native-tvos and Expo TV setup |
| setup-cross-platform.md | MEDIUM | Platform detection and cross-platform caveats |
| setup-architecture.md | MEDIUM | Code sharing and project structure |
| test-strategy.md | MEDIUM | TV testing scope and coverage split |
| test-javascript.md | MEDIUM | JS-level remote/focus test helpers |
| test-e2e.md | MEDIUM | Appium and TV E2E coverage |
| release-cicd.md | MEDIUM | CI, build fingerprinting, and release checks |
Problem → Skill Mapping
| Symptom | Start Here |
|---|---|
| "Focus jumps to wrong element" | focus-management.md → Debugging section |
| "App freezes when scrolling lists" | perf-lists.md → Virtualization |
| "Animations stutter on Fire TV" | perf-animations.md → Native driver |
| "Text too small on TV" | design-typography.md → Minimum sizes |
| "Video won't play / DRM errors" | video-streaming.md → DRM section |
| "Screen reader skips elements" | a11y-implementation.md → Roles & labels |
| "Back button doesn't work right" | nav-patterns.md → Back navigation |
| "Keyboard covers content" | nav-keyboard.md → Built-in vs custom |
| "App takes forever to start" | perf-overview.md → Startup time |
| "Images causing memory crashes" | perf-memory.md → Image optimization |
| "CI pipeline takes hours" | release-cicd.md → Fingerprinting |
| "How to share code across platforms" | setup-architecture.md → Code sharing |
Security (TV-Specific)
General dependency/input hygiene applies as in any RN app; the TV-specific deltas worth calling out:
Never embed FairPlay/Widevine/PlayReady keys in client code — treat the license server as the trust boundary and keep DRM tokens server-issued.
Files
- ATTRIBUTION.mdAdded by AutoGineer879 B
- LICENSELicence file added by AutoGineer1.1 KiB
- SKILL.md10.9 KiB
- agents/openai.yaml307 B
- references/a11y-checklist.md4.3 KiB
- references/a11y-implementation.md4.4 KiB
- references/a11y-overview.md2.8 KiB
- references/design-10foot.md3.0 KiB
- references/design-color.md3.8 KiB
- references/design-layout.md3.0 KiB
- references/design-typography.md2.6 KiB
- references/focus-management.md6.4 KiB
- references/focus-performance.md3.5 KiB
- references/nav-directional.md3.6 KiB
- references/nav-keyboard.md3.6 KiB
- references/nav-patterns.md4.4 KiB
- references/perf-animations.md3.0 KiB
- references/perf-lists.md3.3 KiB
- references/perf-memory.md2.5 KiB
- references/perf-network.md2.7 KiB
- references/perf-overview.md3.6 KiB
- references/release-cicd.md3.2 KiB
- references/setup-architecture.md3.8 KiB
- references/setup-cross-platform.md3.3 KiB
- references/setup-getting-started.md5.1 KiB
- references/test-e2e.md3.6 KiB
- references/test-javascript.md3.7 KiB
- references/test-strategy.md2.3 KiB
- references/video-debugging.md1.6 KiB
- references/video-players.md3.2 KiB
- references/video-streaming.md2.1 KiB
references/nav-directional.md
title: Directional Navigation Fundamentals impact: CRITICAL tags: navigation, directional, focus-engine, d-pad, spatial-navigation, tv
Directional Navigation Fundamentals
Every TV app starts with a simple question: where does the focus go next? When a viewer presses an arrow on the remote, the app must decide which element becomes active.
Quick Reference
TV navigation is fundamentally physical — each button press is deliberate
Platform focus engines differ: tvOS uses spatial inference, Android TV uses proximity, web-based TVs need JS libraries
Design layouts that work with the focus engine, not against it
Align and space elements logically so directional presses resolve to the intended neighbor
How Focus Engines Work
tvOS — High Precision
Apple's engine examines layout geometry:
Searches for focusable views based on spatial proximity in the pressed direction
Treats related items as "focus islands" (cohesion zones)
Expects clean grid/alignment patterns
When layouts are clean: focus slides and decelerates like real physics
Account for diagonal movement and inertia-based swipes
Android TV — Developer-Defined
More flexible, leans on developer direction:
Focus moves to nearest visible item along pressed direction (Cartesian)
Override with
nextFocusUp,nextFocusDown,nextFocusLeft,nextFocusRightTolerates less regular layouts
When no valid target exists, focus can disappear
Vega OS
Same Cartesian focus management as Android TV — focus moves to "closest" item in D-pad direction.
Web-Based TVs (Tizen, webOS)
No native focus engine — must use JavaScript spatial navigation:
@noriginmedia/norigin-spatial-navigationis the most popular libraryKeeps a registry of focusable nodes
Listens for arrow/enter keys
Decides next target based on geometry and direction
Preferred Approach: Let the Platform Lead
For most apps, the best focus management is no explicit management at all:
<View style={styles.row}>
{items.map((item) => (
<Pressable
key={item.id}
onPress={() => select(item)}
onFocus={() => setFocusedItem(item.id)}
>
<Image source={item.poster} />
</Pressable>
))}
</View>Key strategies:
Align and space elements logically
Avoid dead zones — gaps cause unpredictable jumps
Group related UI into containers ("focus islands")
On tvOS: account for diagonal movement; on Android TV: design for strict up/down/left/right
If focus suddenly behaves strangely, it's usually a sign the layout needs adjusting, not that you need more code.
React Native TV's Focus Tree
Each platform builds a focus tree — an internal map of all focusable elements. Every Pressable, Touchable, or TextInput becomes a node. React Native TV mirrors this with unified focus APIs.
Two Navigation Layers
Global navigation — Moves between main sections (Home, Search, Settings). Typically a drawer.
Local navigation — Operates within a section (Popular, Recommended tabs). Typically tabs.
Building Predictable Navigation
Consistent movement: If "right" moves to next card, keep that everywhere
Let layout lead: Clear alignment helps the engine make right decisions
Plan focus transitions: Define where focus starts, how "back" behaves, what regains focus on return
Shallow hierarchy: Too many layers makes users lose their bearings
Related Skills
focus-management.md — TVFocusGuideView, hasTVPreferredFocus, debugging
nav-patterns.md — Drawer, tabs, modals, back navigation
design-layout.md — Layout patterns that support natural focus flow
Requirements and compatibility
Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta
“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.
Security
No issues found by our static scan· No issues found
A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.
Attribution and licence
- Published by
- Callstack
- Publisher
- Callstack (Official)
- Source
- callstackincubator/agent-skills · skills/react-native-tv-best-practices · commit 59e9d17
- Licence
- MIT License (redistribution allowed)
- LICENSE (added by AutoGineer from LICENSE)
- ATTRIBUTION.md (written by AutoGineer)
- Synced
AutoGineer is not affiliated with or endorsed by Callstack.
Related skills
Web Artifacts Builder
AnthropicOfficial
A structured workflow for developing and bundling complex, multi-component React artifacts for Claude.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreApache-2.0Medium riskHas scriptsGitHub stars of the source repository188.6k
Frontend UI Engineering
Addy Osmani· Community
Engineering standards for building accessible, responsive, and production-ready frontend user interfaces.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository113.9k
Ask Sonner
Emil Kowalski· Community
A comprehensive guide for implementing, styling, and troubleshooting the Sonner toast notification library in React applications.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository54.3k
Pick UI Library
Emil Kowalski· Community
Get recommendations for frontend UI libraries based on a curated, opinionated list.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository54.3k
Animate Expo
Emil Kowalski· Community
A senior mobile engineering guide for building React Native and Expo animations that feel correct on real devices.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository54.3k
Prototype
Emil Kowalski· Community
A design engineering workflow for building and comparing distinct UI variants using an isolated picker harness.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository54.3k
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download react-native-tv-best-practices.zip