Building Instagram Reels-style video feeds in React Native with reels-kit

Reels-kit is an open-source React Native toolkit designed for creating vertical video feeds with features like snap paging, bounded video players, tap and scrub gestures, and pluggable video adapters. The toolkit aims to simplify the implementation of a vertical video feed, which can quickly become complex due to the need for native video players for each cell.

As users scroll through multiple videos, each video may require its own decoder, leading to performance issues. Additionally, videos continue playing when the user navigates to another screen or sends the app to the background. Rapid swiping can cause the progress bar to jump instead of moving smoothly. The toolkit provides solutions to these issues by offering a headless building block around a FlashList-based feed, allowing developers to focus on the layout while handling the difficult parts.

Reels-kit consists of small, reusable components that work together to create a functional video feed. It measures the page height from the container instead of the window, enabling snap paging where one swipe moves one reel. Bounded players ensure that only the active reel and its neighboring reels mount a native player, improving performance by limiting the number of decoders in use.

Playback is paused when the reel is not active, the screen is unfocused, or the app is in the background. The toolkit supports tap to mute, optional double tap to like, and a drag-to-seek progress bar. It also handles failed loads by displaying a thumbnail until the video is ready, a buffering slot, and a retry option that remounts the player.

Users can bring their own video engine, as reels-kit does not include a default video library. The toolkit is built on FlashList 2, Reanimated 4, and Gesture Handler 3, making it compatible with React Native 0.82 or newer with the New Architecture. To use reels-kit, developers need to install several dependencies, including reels-kit, @shopify/flash-list, react-native-reanimated, react-native-worklets, and react-native-gesture-handler.

After installation, three setup steps are required: adding the worklets plugin to babel.config.js, wrapping the app in GestureHandlerRootView, and running pod install in the ios/ directory. A compatibility note is that Reanimated must match the React Native version, as different versions have different requirements.