Customizable, lightweight React Native carousel component with accessibility support.

Pinar is a lightweight and customizable React Native carousel component that works well when creating simple image sliders or app onboarding flows.

If you need more advanced things like animations, lazy loading of images, or parallax, then please consider using a library like react-native-reanimated-carousel.

Table of contents

• Install
• Basic example
• More examples
• Properties
  • Basic carousel properties
  • Callbacks
  • Methods
  • Custom styling properties
  • Custom render properties
  • Properties of <ScrollView />
• Dependencies
• Development
• Automated tests
• Special thanks
• License

Install

yarn add pinar --save

## or
## npm install pinar --save

Basic example

import React from "react";
import { Text, View } from "react-native";
import Carousel from "pinar";

const styles = {
  slide1: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
    backgroundColor: "#a3c9a8"
  },
  slide2: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
    backgroundColor: "#84b59f"
  },
  slide3: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
    backgroundColor: "#69a297"
  },
  text: {
    color: "#1f2d3d",
    opacity: 0.7,
    fontSize: 48,
    fontWeight: "bold"
  }
};

export default () => (
  <Carousel>
    <View style={styles.slide1}>
      <Text style={styles.text}>1</Text>
    </View>
    <View style={styles.slide2}>
      <Text style={styles.text}>2</Text>
    </View>
    <View style={styles.slide3}>
      <Text style={styles.text}>3</Text>
    </View>
  </Carousel>
);

Result:

More examples

The /examples folder has a React Native app that you can run on your machine to see the carousel being used with a lot of different options.

If you don't want to run the app, you can have a look at the components folder for example components.

Properties

Basic carousel properties

Callbacks

Use these properties to be notified when the user scrolls the carousel or changes the page.

Methods

To use methods you need to get a reference to the carousel inside your React class component.

<Carousel
  ref={carousel => {
    this.carousel = carousel;
  }}
/>

You can then call the method from outside the carousel:

<Button
  title="scroll to next page"
  onPress={() => {
    this.carousel.scrollToNext();
  }}
/>

Custom styling properties

Use these properties to customize how the carousel is styled.

Set the mergeStyles property to true if you want to merge your custom styles with the default ones instead of having define all the needed styles. You can also import { defaulStyles } from "pinar" to get access to the default styles and use them as defaults.

Have a look at the "custom styles" component and "custom styles with merge" component for an example.

Custom render properties

Use these properties to provide your own functions render custom elements instead of the default ones. Have a look at the custom rendering component for an example.

Properties of <ScrollView />

These properties are exposed from <ScrollView />. You can provide your own properties if you want to customize it.

for more info: http://facebook.github.io/react-native/docs/scrollview.html

Dependencies

No other dependencies than React Native.

Development

If you want help out with the development of this library, bug reports and fixes are very welcome. If you are thinking about a new feature, please open a feature request issue first to verify that implementing it makes sense.

How to develop locally

First make sure that you have Node.js, Yarn and React Native installed. It is also a good idea to have Xcode and/or Android Studio installed to be able to run the iOS simulators / Android emulators.

If you choose to install emulators or simulators, you can use the example app to test your changes in a React Native app.

Automated tests

When making changes to the code, please add a unit test or a functional test to verify that the code is working. The test runner that the project uses is Jest, Enzyme is used to test React Components, and Detox is used to run functional tests against the project's example app. The command to run unit tests is yarn test and the command to run functional tests is yarn functional.

Before you submit the code for a Pull Request, make sure that you run yarn test, yarn tsc, and yarn lint to verify that unit tests pass and both the Typescript type checking and ESLint linting are not printing any errors.

Special thanks

Special thanks for these libraries for providing inspiration for code and other things:

• react-native-swiper - Inspiration for the code and the library API.
• react-native-snap-carousel - Inspiration for the library API and naming.
• svgr - Inspiration for the issue labels and issue templates.

License

MIT