react-native-carousel-lite

react-native-carousel-lite

Lightweight, zero-dependency React Native carousel component. Fast, customizable slider with autoplay, infinite loop, and pagination—built with ScrollView for iOS and Android.

react-native-carousel-lite is a minimal, high-performance carousel for React Native with no third-party dependencies. Use it as a lightweight alternative to heavier carousel libraries when you need a simple, fast slider or image carousel with snap scrolling, optional autoplay, and full TypeScript support.

Table of contents

• Preview
• Why this carousel?
• Features
• Installation
• Usage
• Props
• FAQ

• License

✨ Preview

Why this carousel?

Best React Native carousel for small bundles. Many carousels depend on reanimated, gesture handlers, or native modules. This one uses only the built-in ScrollView with pagingEnabled, so you get a zero-dependency carousel that stays fast and predictable on iOS and Android. Ideal when you need a lightweight carousel or snap carousel without extra native setup.

⚡ Features

• Zero dependencies — Pure React Native; no carousel or gesture libraries
• High performance — ScrollView-based; no reanimated or native modules
• Smooth snap scrolling — Page-by-page with configurable deceleration
• Autoplay & infinite loop — Configurable interval; optional looping
• Cross-platform — Works on iOS and Android
• Fully customizable — Styles and custom dot renderer for pagination
• Controlled or uncontrolled — index / onIndexChange or internal state
• Ref API — scrollToIndex, scrollToNext, scrollToPrev, getCurrentIndex
• Tappable pagination dots — Tap a dot to jump to that page; custom renderDot receives onPress
• Accessibility — Configurable labels and roles
• Windowed rendering — Optional windowSize for large lists

📦 Installation

Install the package from npm:

npm install react-native-carousel-lite

Or with Yarn:

yarn add react-native-carousel-lite

Peer dependencies: React >=17.0.0, React Native >=0.64.0. No native linking required.

🚀 Usage

Basic carousel

Import the carousel, pass your data and renderItem. Pagination dots are shown by default.

import { Carousel } from 'react-native-carousel-lite';
import { Text, View } from 'react-native';

const data = [{ id: '1', title: 'Slide 1' }, { id: '2', title: 'Slide 2' }];

<Carousel
  data={data}
  renderItem={({ item }) => <Text>{item.title}</Text>}
  keyExtractor={(item) => item.id}
  itemsPerPage={2}
  autoPlay
  autoPlayInterval={3000}
  loop
  onIndexChange={(index) => console.log(index)}
/>

Scroll control with ref

Use a ref to scroll to a specific slide or next/prev (e.g. from buttons).

const ref = useRef<CarouselRef>(null);

<Carousel ref={ref} data={data} renderItem={...} />

// Later:
ref.current?.scrollToIndex(2, true);
ref.current?.scrollToNext(true);
ref.current?.scrollToPrev(true);
ref.current?.getCurrentIndex();

Controlled index

Control the current page from parent state (e.g. sync with tabs or URL).

const [index, setIndex] = useState(0);
<Carousel
  data={data}
  index={index}
  onIndexChange={setIndex}
  renderItem={...}
/>

Vertical carousel and custom dots

Use vertical for vertical scrolling and renderDot for custom pagination UI.

<Carousel
  data={data}
  vertical
  renderItem={...}
  renderDot={({ index, isActive, onPress }) => (
    <Pressable onPress={onPress} style={[styles.dot, isActive && styles.dotActive]} />
  )}
/>

📋 Props

Prop	Type	Default	Description
data	T[]	required	Array of items to display in the carousel.
renderItem	(params) => ReactNode	required	Renders each item; receives { item, index }.
itemsPerPage	number	1	Number of items per page (stacked in scroll direction).
autoPlay	boolean	false	When true, advances to the next page at autoPlayInterval.
autoPlayInterval	number	5000	Auto-advance interval in milliseconds.
autoPlayPauseOnDrag	boolean	true	Pauses autoplay while the user is dragging.
keyExtractor	(item, index) => string	index	Returns a stable key for each item.
index	number	—	Controlled current page index (use with onIndexChange).
defaultIndex	number	0	Initial page when using uncontrolled mode.
onIndexChange	(index) => void	—	Called when the visible page index changes.
loop	boolean	false	Enables infinite looping (duplicates first/last page).
vertical	boolean	false	When true, scrolls vertically instead of horizontally.
decelerationRate	'fast' | 'normal' | number	'fast'	Scroll deceleration for snappier feel.
containerStyle	ViewStyle	—	Style for the outer container.
contentContainerStyle	ViewStyle	—	Style for the ScrollView content container.
pageStyle	ViewStyle	—	Style for each page wrapper.
showDots	boolean	true	Whether to show pagination dots.
renderDot	({ index, isActive, onPress }) => ReactNode	—	Custom dot renderer; receives onPress to scroll to that page. Overrides default dot styles when set.
dotsContainerStyle	ViewStyle	—	Style for the dots container.
dotStyle	ViewStyle	—	Style for inactive dots.
activeDotStyle	ViewStyle	—	Style for the active dot.
windowSize	number	0	Render only pages within active ± N (0 = render all). Use for large lists.
accessibilityLabel	string	'Carousel'	Accessibility label for the carousel.
dotsAccessibilityLabel	string	'Page indicator'	Accessibility label for the pagination.

❓ Frequently asked questions

How do I install a carousel in React Native?
Run npm install react-native-carousel-lite, then import Carousel and pass data and renderItem. No native linking or extra setup.

Is this carousel zero dependency?
Yes. It only uses React Native’s built-in ScrollView. No reanimated, gesture handler, or other carousel libraries.

Does it work on iOS and Android?
Yes. It’s built with core React Native components and works on both platforms.

Can I use it as an alternative to other similar carousel libraries?
Yes. If you want a lighter, ScrollView-based carousel without extra native modules, this is a good fit. Use the ref API for programmatic scrolling and the props table above for full options.

📄 License

MIT © Anshul Thakur 2026

• npm: react-native-carousel-lite
• GitHub: garganshul9200/react-native-carousel-lite