Sunsama Infinite Horizontal Swiper

A highly efficient infinite horizontal swiper component designed for the Sunsama mobile app. This library enables smooth, responsive swiping through items (cards) with a natural gesture-based experience.

Note: This README is generated by AI.

Features

• Infinite swiping: Enjoy endlessly scrolling through items.
• Spring-based animation: Smooth and natural motion using a physics simulation.
• Custom rendering: Render cards with a custom function that supports a focused state.
• Callback support: Respond to index changes with worklet callbacks.
• Imperative control: Programmatically scroll to a specific index using exposed methods.

Installation

Install the package via npm or yarn:

npm install @sunsama/infinite-horizontal-swiper

Or:

yarn add @sunsama/infinite-horizontal-swiper

Requirements

It might work on any other Reanimated/Gesture Handler version, but it is only tested on the following versions:

• React Native >= 0.79.2
• React Native Reanimated >= 3.17.5
• React Native Gesture Handler >= 2.25.0

Usage

Check out the app in the example folder for a working demo. The example app demonstrates how to use the InfiniteHorizontalSwiper component in a React Native application.

API Reference

Props

| Prop | Type | Description | Default | |-------------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------|---------| | renderItem | (index: number, isFocused: boolean) => ReactNode | A function to render each card. It receives the index of the card and a flag indicating whether the card is focused. | — | | windowSize | number | Number of cards to display at once. Must be an odd number greater than 1. Adjusting this can help balance performance and UI smoothness. | 3 | | onIndexChangedWorklet | (index: number) => void | A Reanimated worklet function called when the index changes. Use this callback to respond to changes in focus. | — | | initialIndex | number | The index of the card that should be focused initially. | 0 |

Reference Methods

After attaching a ref to the component (using React.forwardRef), the following method is available:

scrollToIndex

scrollToIndex: (index: number) => void;

Programmatically scrolls the swiper to focus the card at the specified index with a smooth spring animation.

Contributing

We welcome contributions, issues, and feature requests! Feel free to check the GitHub issues page to get started. For feature requests mind you that this is mainly used by us internally, so we might not be able to prioritize your request. We're happy if you want to add a feature yourself and send us a PR.

License

This project is open source and available under the MIT License.