React Native Swiper Component

1.6.0 · active · verified Tue Apr 21

react-native-swiper is a widely used, feature-rich swiper/carousel component designed for React Native applications. As of its latest stable release, v1.6.0, it provides a highly customizable solution for displaying paginated content, supporting both iOS and Android platforms. The library focuses on providing a smooth user experience with features like autoplay, infinite looping, flexible pagination dots, and lazy loading for performance optimization via `loadMinimal`. It supports TypeScript out-of-the-box, shipping with correct type definitions, and has recently moved away from `ViewPagerAndroid` to `ScrollView` for improved compatibility and reduced dependency footprint. The project maintains an active development pace with consistent bug fixes and new features, though no strict release cadence is formally documented. Its key differentiators include extensive prop-based customization for styling and behavior, robust platform support, and a history of addressing common React Native carousel challenges.

Common errors

```
Uncaught TypeError: _this.refs.scrollView.scrollTo is not a function
```
cause This error typically occurred in `react-native-swiper` versions prior to 1.5.12 due to issues with accessing the internal `scrollView` ref or its `scrollTo` method.

fix Upgrade `react-native-swiper` to version 1.5.12 or newer. Ensure your component structure allows for proper ref forwarding if you are wrapping the `Swiper` component.
```
Swiper content not rendering correctly or experiencing layout issues after device rotation on Android.
```
cause Incorrect calculation of component width and height after orientation changes, particularly on Android, was a known bug in older versions.

fix Upgrade `react-native-swiper` to v1.5.13 or newer, which includes fixes for recalculating dimensions correctly on layout changes and device rotations.
```
The `index` prop on iOS does not correctly initialize or update the swiper's current page.
```
cause An issue existed in versions prior to 1.5.10 where the `index` prop was not reliably setting or updating the initial slide on iOS.

fix Upgrade `react-native-swiper` to version 1.5.10 or newer to resolve the `index` prop initialization and update issues on iOS.

Warnings

breaking The `style` prop for the Android swiper container was renamed to `containerStyle` in v1.6.0. Directly applying `style` to the `Swiper` component for its container will no longer work on Android.
Fix: Replace `style={...}` with `containerStyle={...}` when targeting the swiper's outer container on Android.
breaking The internal dependency on `ViewPagerAndroid` was removed in v1.6.0, in favor of using React Native's `ScrollView`. This change may require cleaning old `node_modules` and re-installing dependencies.
Fix: Run `npm install --save react-native-swiper@next` and consider clearing `node_modules` and reinstalling to ensure the old `ViewPagerAndroid` reference is gone.
gotcha Older versions (prior to v1.5.5) utilized `React.PropTypes`, which has been deprecated in modern React. v1.5.5 updated to use the separate `prop-types` package.
Fix: Upgrade to v1.5.5 or newer. If stuck on an older version, ensure `prop-types` is installed and properly configured, or be aware of console warnings related to deprecated PropTypes usage.
gotcha Issues were reported in older versions (fixed in v1.6.0-rc) where the Swiper's internal state could be messed up when a parent component frequently calls `setState`, leading to unexpected behavior or visual glitches.
Fix: Upgrade to `react-native-swiper` v1.6.0 or newer. If upgrading is not immediately possible, carefully manage parent component re-renders that might affect the Swiper's props or state.
gotcha Compatibility for ES6 and CommonJS was improved significantly in `v1.6.0-rc`. Older versions might exhibit less robust behavior in mixed module environments or with specific bundler configurations.
Fix: For optimal module compatibility, especially in modern React Native projects, ensure you are on `react-native-swiper` v1.6.0 or later.

Install

npm install react-native-swiper npm
yarn add react-native-swiper yarn
pnpm add react-native-swiper pnpm

Imports

Swiper
wrong:
```
const Swiper = require('react-native-swiper')
```
correct:
```
import Swiper from 'react-native-swiper'
```
While CommonJS `require` might work in some React Native setups, `import` is the idiomatic and recommended way, especially for modern ES module environments and TypeScript.
SwiperProps
wrong:
```
import { SwiperProps } from 'react-native-swiper'
```
correct:
```
import type { SwiperProps } from 'react-native-swiper'
```
When importing only types, use `import type` for better tree-shaking and explicit declaration, especially with TypeScript 3.8+.

Quickstart

This example demonstrates a basic `Swiper` component with three slides, infinite loop, autoplay, and navigation buttons.

import React from 'react';
import { View, Text, StyleSheet } from 'react-native';
import Swiper from 'react-native-swiper';

const App = () => {
  return (
    <Swiper style={styles.wrapper} showsButtons loop autoplay>
      <View style={styles.slide1}>
        <Text style={styles.text}>Hello Swiper</Text>
      </View>
      <View style={styles.slide2}>
        <Text style={styles.text}>Beautiful</Text>
      </View>
      <View style={styles.slide3}>
        <Text style={styles.text}>And simple</Text>
      </View>
    </Swiper>
  );
};

const styles = StyleSheet.create({
  wrapper: {},
  slide1: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: '#9DD6EB',
  },
  slide2: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: '#97CAE5',
  },
  slide3: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: '#92BBD9',
  },
  text: {
    color: '#fff',
    fontSize: 30,
    fontWeight: 'bold',
  }
});

export default App;

view raw JSON →