react-tv-space-navigation

• Why?
• What you can achieve
• How to use
• How to run the example
• API documentation
• Pitfalls
• Accessibility support
• Contributing

Why?

Spatial navigation is a hard problem on a TV app. Many solutions exist. React Native TV even has a core solution for it. But most existing solutions are not 100% cross-platform.

If you’re looking to develop a TV app for AndroidTV, tvOS, and web-based TV devices, this package can be a valuable tool. However, if you don’t require web support, using the native react-native-tvos solution might be a better fit. The primary objective of this package is to provide consistent support across all platforms, though this comes with some trade-offs (see the pitfalls below).

The library is based on LRUD, which is a UI-agnostic lib that represents spatial navigation. The library is a React wrapper around the core logic of LRUD.

What you can achieve

Check out the live web demo!

One of the goals of the lib is to have a simple and declarative API. No need for hooks or dark shenanigans. You just simply declare components.

Here's the kind of code you'll be able to achieve:

1/**
2 * A simple component that shows a rabbit program
3 * We plug it to the Spatial Navigation easily using a FocusableView
4 */
5const Rabbit = ({ onSelect }) => (
6  <SpatialNavigationFocusableView onSelect={onSelect}>
7    {({ isFocused }) => <RabbitLayout isFocused={isFocused} />}
8  </SpatialNavigationFocusableView>
9);
10
11/**
12 * We can have as many nodes as we want. We group our rabbits in a horizontal spatial navigation view
13 * to spatially describe a row layout
14 * (it includes a spatial navigation node AND the horizontal styling for it)
15 *
16 * We also want to scroll horizontally, so we add a horizontal scrollview.
17 */
18const RabbitRow = () => (
19  <SpatialNavigationScrollView horizontal>
20    <SpatialNavigationView direction="horizontal">
21      {/* assuming you have rabbits data */}
22      {rabbits.map((_, index) => (
23        <Rabbit onSelect={() => console.log('selected rabbit ', index)} />
24      ))}
25    </SpatialNavigationView>
26  </SpatialNavigationScrollView>
27);
28
29/**
30 * Now I simply add a page with a Root node and a vertical scroll view to scroll through my rows.
31 */
32const Page = () => (
33  <SpatialNavigationRoot>
34    <SpatialNavigationScrollView>
35      <RabbitRow />
36      <RabbitRow />
37      <RabbitRow />
38      <RabbitRow />
39      <RabbitRow />
40      <RabbitRow />
41    </SpatialNavigationScrollView>
42  </SpatialNavigationRoot>
43);

How to use

You should follow the tutorial.

How to run the example

If you want to run the example app in packages/example, take a look at the README

API documentation

You can have a look at the documentation.

Pitfalls & troubleshooting

You should have a look at the pitfalls and troubleshooting.

Accessibility support

Read the state of accessibility.

Contributing

Publishing the package

• Increment the package.json in ./packages/lib/package.json.
• Commit the change git commit -m "chore: bump version"
• Add a tag matching the version git tag vx.x.x && git push --tags
• Generate the changelog and commit it yarn changelog && git add CHANGELOG.md && git commit "chore: update changelog"
• Then publish the package:

cd packages/lib
yarn publish:package