@code-atlas/react-native-snap-carousel
Version:
Swiper/carousel component for React Native with previews, multiple layouts, parallax images, performant handling of huge numbers of items, and RTL support. Compatible with Android & iOS.
97 lines (80 loc) • 5.94 kB
Markdown
# `<Pagination />` component
Starting with version `2.4.0`, a customizable `<Pagination />` component has been added. This is how it looks like with its default configuration:
## Table of contents
1. [Props](#props)
1. [Note on dots' colors](#note-on-dots-colors)
1. [Usage](#usage)
## Props
Prop | Description | Type | Default
------ | ------ | ------ | ------
**`activeDotIndex`** | Index of the currently active dot | Number | **Required**
**`dotsLength`** | Number of dots to display | Number | **Required**
`activeOpacity` | Opacity of the dot when tapped. The prop has no effect if `tappableDots` hasn't been set to `true`. | Number | 1
`carouselRef` | Reference to the `Carousel` component to which pagination is linked. Needed only when setting `tappableDots` to `true`. | Object | `undefined`
`containerStyle` | Style for dots' container that will be merged with the default one | View Style Object | `{}`
`dotColor` | Background color of the active dot. **Use this if you want to animate the change between active and inactive colors**, and always in conjunction with `inactiveDotColor` (see [notes](#dots-colors)). | String | `undefined`
`dotContainerStyle` | Style of each dot's container. Use this if you need to specify styles that wouldn't have any effect when defined with `dotStyle` (such as `flex`). | View Style Object | `{}`
`dotElement` | Optional custom active dot element that will replace the default one. The element will receive a prop `active` set to `true` as well as a prop `index`. | React element | `undefined`
`dotStyle` | Dots' style that will be merged with the default one | View Style Object | `{}`
`inactiveDotColor` | Background color of the inactive dots. **Use this if you want to animate the change between active and inactive colors**, and always in conjunction with `dotColor` (see [notes](#dots-colors)). | String | `undefined`
`inactiveDotElement` | Optional custom inactive dot element that will replace the default one. The element will receive a prop `active` set to `false` as well as a prop `index` | React element | `undefined`
`inactiveDotOpacity` | Value of the opacity effect applied to inactive dots | Number | `0.5`
`inactiveDotScale` | Value of the 'scale' transform applied to inactive dots | Number | `0.5`
`inactiveDotStyle` | Dots' style that will be applied to inactive elements | View Style Object | `{}`
`renderDots` | Function that gives you complete control over pagination's rendering. It will receive three parameters : `(activeIndex, total, context)`. This can be especially useful in order to replace dots with numbers. **:warning: You will need to provide your own logic to handle taps. See [this comment](https://github.com/meliorence/react-native-snap-carousel/issues/273#issuecomment-368295203) for more info.** | Function | `undefined`
`tappableDots` | Make default dots tappable, e.g. your carousel will slide to the corresponding item. Note that `carouselRef` must be specified for this to work. | Boolean | `false`
`vertical` | Whether to layout dots vertically or horizontally | Boolean | `false`
`animatedDuration` | Length of dot animation (milliseconds) | Number | `250`
`animatedFriction` | Controls "bounciness"/overshoot on dot animation | Number | `4`
`animatedTension` | Controls speed dot animation | Number | `50`
`delayPressInDot` | Delay in ms, from the start of the touch, before onPressIn is called on dot | Number | `0`
## Note on dots' colors
If your active and inactive dots aren't of the same color, you have a choice to make:
1. either animate the color transition by specifying both `dotColor` and `inactiveDotColor`
1. or setting `{ backgroundColor }` in both `dotStyle` and `inactiveDotStyle`.
**When animating the color transition, the dot component will no longer be able to use the native driver for scale and opacity transitions.** As stated in [React Native's doc](https://facebook.github.io/react-native/docs/animations.html#caveats), color animations aren't supported by the native driver. And, unfortunately, it doesn't seem currently possible to run native-powered and js-powered animations at the same time on the same element.
Basically, this is a tradeoff between color transition and optimal smoothness. We recommended you to try the first version and, if you experiment performance drops, to settle for the second one.
## Usage
Since `<Pagination />` is, purposely, a separated component, you need to connect it to your `<Carousel />` component manually. This is pretty straightforward, but here is an example to get you started.
```javascript
import Carousel, { Pagination } from 'react-native-snap-carousel';
export default class MyCarousel extends Component {
_renderItem ({item, index}) {
return <MySlideComponent data={item} />
}
get pagination () {
const { entries, activeSlide } = this.state;
return (
<Pagination
dotsLength={entries.length}
activeDotIndex={activeSlide}
containerStyle={{ backgroundColor: 'rgba(0, 0, 0, 0.75)' }}
dotStyle={{
width: 10,
height: 10,
borderRadius: 5,
marginHorizontal: 8,
backgroundColor: 'rgba(255, 255, 255, 0.92)'
}}
inactiveDotStyle={{
// Define styles for inactive dots here
}}
inactiveDotOpacity={0.4}
inactiveDotScale={0.6}
/>
);
}
render () {
return (
<View>
<Carousel
data={this.state.entries}
renderItem={this._renderItem}
onSnapToItem={(index) => this.setState({ activeSlide: index }) }
/>
{ this.pagination }
</View>
);
}
```