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://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/a11y-implementation.md
title: Accessibility Implementation in React Native TV impact: HIGH tags: accessibility, screen-reader, focus, voiceover, talkback, tv
Accessibility Implementation in React Native TV
Quick Reference
For agent-run checks, load the
agent-deviceskill first, then readagent-device help workflowUse
agent-deviceaccessibility-tree evidence to inspect exposed labels, roles, states, focus, and modal behaviorUse manual screen-reader testing only for spoken-output timing, audio behavior, and platform quirks that automation cannot prove
Do not put
accessible={true}high in a modal/body tree; it collapses focusable children into one itemPrefer
TVFocusGuideViewfor shared focus paths; usenextFocus*only as a targeted overrideAwait
AccessibilityInfo.isScreenReaderEnabled()before muting autoplay or changing announcementsPair visual-only remote feedback with an accessibility announcement when state changes
Agent-Run Accessibility Smoke
Before planning or running device automation, load the agent-device skill and follow its setup/help flow. Do not duplicate command recipes here; use the installed agent-device help for current command shapes and platform limits.
An AI agent should not claim it heard VoiceOver, TalkBack, or VoiceView. Instead, use agent-device to inspect what the app exposes to platform accessibility. Check the accessibility-tree evidence for:
Interactive controls expose useful labels, roles, enabled/disabled state, and selected/checked state
The currently focused element is the expected remote target after each D-pad press
Modal opening moves focus inside the modal and hides or de-prioritizes background controls
Closing a modal restores focus to the invoking control or another predictable target
Dynamic state changes expose updated labels/state or a live-region/announcement path
Escalate to manual screen-reader testing for the parts agent-device cannot verify: exact spoken order, announcement timing, audio-description behavior, caption rendering, and platform-specific verbosity.
Accessible Modals
<Modal
visible={isVisible}
accessibilityViewIsModal={true}
onRequestClose={handleClose}
>
<View>
{/* Don't wrap the body in `accessible` — it collapses children into one
element and hides the buttons from focus. Label a header node instead. */}
<Text accessibilityRole="header">Continue watching?</Text>
<Text>Are you still watching?</Text>
<Button title="Yes" onPress={handleContinue} />
<Button title="No" onPress={handleExit} />
</View>
</Modal>Set initial focus inside modal
Trap focus within modal
Announce dialog opening
Autoplay Content
Include remote-focusable playback controls
AccessibilityInfo.isScreenReaderEnabled()returns a Promise —awaitit (or subscribe to thescreenReaderChangedevent) before deciding whether to mute; a bare synchronousifis always truthy:const srOn = await AccessibilityInfo.isScreenReaderEnabled(); if (srOn) muteAutoplay();Apple TV: respect system audio focus, integrate with
AVAudioSession
Cross-Platform Focus
Prefer TVFocusGuideView over nextFocus* for shared layouts. destinations takes an array of resolved components (ref.current), not the ref objects and not string IDs. Don't build it inline — ref.current is null on the first render and mutating a ref triggers no re-render, so the guide would register nothing. Hoist the resolved components into state once the children have mounted:
const playRef = useRef(null);
const infoRef = useRef(null);
const [destinations, setDestinations] = useState([]);
// Children assign their refs after this component first renders; push the
// resolved nodes into state so a NEW array is passed and the guide updates.
useEffect(() => {
setDestinations([playRef.current, infoRef.current].filter(Boolean));
}, []);
<TVFocusGuideView destinations={destinations}>
<TouchableOpacity ref={playRef} accessibilityRole="button" accessibilityLabel="Play" />
<TouchableOpacity ref={infoRef} accessibilityRole="button" accessibilityLabel="Info" />
</TVFocusGuideView>See focus-management.md for when nextFocus* overrides are acceptable.
Related Skills
a11y-overview.md — Accessibility fundamentals for TV
a11y-checklist.md — Pre-launch checklist
focus-management.md — Focus APIs
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 or 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
Anti UI Slop
GitHubOfficial
Prevent generic AI-generated UI by grounding interface development in real-world design patterns and rigorous review gates.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreApache-2.0GitHub stars of the source repository40.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
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download react-native-tv-best-practices.zip