react-native-snap-carousel

✨ Some great news for you, fellow plugin user!

💡 Head over there now to learn more about all the goodness that's coming your way.

Table of contents

1. Showcase
2. Usage
3. Example
4. Props, methods and getters
5. Layouts and custom interpolations
6. ParallaxImage component
7. Pagination component
8. Tips and tricks
9. Known issues
10. Important note regarding Android
11. Important note regarding iOS
12. Roadmap
13. Credits

Showcase

:raised_hands: New feature: layouts

Do you want to find out more?

Real-world examples

These are live apps we've created that make heavy use of the plugin. Don't be shy, share yours if you've done something awesome with it!

:handshake: Maintainers wanted

Hey there,

Creating and maintaining this plugin has been a fun ride that started in 2016. We thank you all for your appreciation and for making the most out of it! You've motivated us to spend countless hours improving the plugin, and made us happy to give back to the Open Source community.

Put simply, we love this project. However we currently aren't able to give it the love it deserves and the care it requires. If you have enough time and knowledge, and want to become a maintainer, please let us know.

💡 Just head there if you're interested.

We're not abandoning the ship, but we need more people to help us keep it alive and well!

Usage

$ npm install --save react-native-snap-carousel

If you're using Typescript you should also install type definitions:

$ npm install --save @types/react-native-snap-carousel

import Carousel from 'react-native-snap-carousel';

export class MyCarousel extends Component {

    _renderItem = ({item, index}) => {
        return (
            <View style={styles.slide}>
                <Text style={styles.title}>{ item.title }</Text>
            </View>
        );
    }

    render () {
        return (
            <Carousel
              ref={(c) => { this._carousel = c; }}
              data={this.state.entries}
              renderItem={this._renderItem}
              sliderWidth={sliderWidth}
              itemWidth={itemWidth}
            />
        );
    }
}

Example

Here are simple examples that can be edited in real time in your browser:

• https://snack.expo.io/@vitkor/carousel-simple-example
• https://snack.expo.io/@bd-arc/react-native-snap-carousel-%7C-example-with-custom-interpolations

You can also find a more in-depth (read "complex") one in the /example folder.

Props, methods and getters

In order to let you to create mighty carousels and to keep up with your requests, we add new features on a regular basis. Consequently, the list of available props has become really huge and deserves a documentation of its own.

:books: Documentation for "Props, methods and getters"

Layouts and custom interpolations

Built-in layouts

In version 3.6.0, we've added two new layouts on top of the original one: the first one is called 'stack' since it mimics a stack of cards, and the other one is called 'tinder' since it provides a Tinder-like animation.

You can choose between the three of them using the new prop layout and you can modify the default card offset in the 'stack' and 'tinder' layouts with prop layoutCardOffset.

<Carousel layout={'default'} />

<Carousel layout={'stack'} layoutCardOffset={`18`} />

<Carousel layout={'tinder'} layoutCardOffset={`9`} />

A few things worth noting:

• As you can see, the effect had to be inverted on Android. This has to do with a really annoying Android-specific bug.
• Even though the new layouts have been created with horizontal carousels in mind, they will also work with vertical ones \o/
• :warning: You should NOT use stack or tinder layouts if you have a large data set to display. In order to avoid rendering issues, the carousel will use a ScrollView component rather than a FlatList one for those layouts (see prop useScrollView). The tradeof is that you won't benefit from any of FlatList's advanced optimizations. See this issue for workarounds; or you may want to implement your own custom interpolation.

Custom interpolations

On top of the new layouts, we've exposed the logic we used so that users can create their own awesome layouts! If you're interested, take a deep breath and dive into the dedicated documentation.

:books: Documentation for "Custom interpolations"

Here are a few examples of what can easily be achieved (you can explore the source code and try it live in the provided example):

ParallaxImage component

Version 3.0.0 introduced a <ParallaxImage /> component, an image component aware of carousel's current scroll position and therefore able to display a nice parallax effect (powered by the native driver to ensure top-notch performance).

:books: Documentation for "ParallaxImage component"

Pagination component

Starting with version 2.4.0, a customizable <Pagination /> component has been added. You can see below how it looks like with its default configuration.

:books: Documentation for "Pagination component"

Tips and tricks

We've gathered together all the useful tips and tricks. There is a bunch of them, which makes this section a must-read!

:books: Documentation for "Tips and tricks"

Known issues

Make sure to read about the known issues before opening a new one; you may find something useful.

:books: Documentation for "Known issues"

Important note regarding Android

Android's debug mode is a mess: timeouts regularly desynchronize and scroll events are fired with some lag, which completely alters the inner logic of the carousel. On Android, you will experience issues with carousel's behavior when JS Dev Mode is enabled, and you might have trouble with unreliable callbacks and loop mode when it isn't. This is unfortunate, but it's rooted in various flaws of ScrollView/FlatList's implementation and the miscellaneous workarounds we had to implement to compensate for it.

:warning: Therefore you should always check if the issue you experience also happens in a production environment. This is, sadly, the only way to test the real performance and behavior of the carousel.

For more information, you can read the following notes: "Android performance" and "Unreliable callbacks".

Important note regarding iOS

:warning: When debugging with the iOS simulator, you're only one "Cmd + T" away from toggling "Slow Animations". If carousel's animations seem painfully slow, make sure that you haven't enabled this setting by mistake.

Roadmap

• <input disabled="" type="checkbox"> Add more examples
• <input disabled="" type="checkbox"> Base the plugin on a component less buggy than FlatList
• <input checked="" disabled="" type="checkbox"> Implement different layouts and allow using custom interpolations
• <input checked="" disabled="" type="checkbox"> Implement both FlatList and ScrollView handling
• <input checked="" disabled="" type="checkbox"> Add the ability to provide custom items animation
• <input checked="" disabled="" type="checkbox"> Implement 'loop' mode
• <input checked="" disabled="" type="checkbox"> Improve Android's behavior
• <input checked="" disabled="" type="checkbox"> Add parallax image component
• <input checked="" disabled="" type="checkbox"> Base the plugin on FlatList instead of ScrollView
• <input checked="" disabled="" type="checkbox"> Add alignment option
• <input checked="" disabled="" type="checkbox"> Add pagination component
• <input checked="" disabled="" type="checkbox"> Add vertical implementation
• <input checked="" disabled="" type="checkbox"> Handle device orientation event (see this note)
• <input checked="" disabled="" type="checkbox"> Add RTL support
• <input checked="" disabled="" type="checkbox"> Improve momemtum handling
• <input checked="" disabled="" type="checkbox"> Improve snap on Android
• <input checked="" disabled="" type="checkbox"> Handle passing 1 item only
• <input checked="" disabled="" type="checkbox"> Fix centering

Credits

Written by Benoît Delmaire (bd-arc) and Maxime Bertonnier (Exilz) at Archriss.

v3.9.1

• Fix for getNode() deprecation warning with RN 0.62+ (thanks @r0b0t3d)

v3.9.0

• Fix for incorrect snapToItem (thanks @Romick2005 & @sergeyzhukov)
• Fix issue with tappable pagination dots (thanks @Creskendoll)
• Clear all timeouts when stopping autoplay (thanks @adrianocola)
• Add props animatedDuration, animatedFriction, animatedTension and delayPressInDot to the Pagination component (thanks @muhlenbrock)

v3.8.4

• Remove TypeScript definitions since they were causing issues (thanks @radko93)
  • If you're using Typescript you should install the type definitions this way: npm install --save @types/react-native-snap-carousel

v3.8.3

• Seems like it's time to remove the getItemLayout & initialScrollIndex override to properly display the first item when its index is a huge number (thanks @rontalx)
  • :warning: Make sure to read how these props work together (link#1 & link #2), and to understand why they were disabled in the first place!
• Fix snapToItem not working when enableMomentum is set to true on Android (thanks @daaashleywch)
• Add basic TypeScript support (thanks @facuacostag)
• Stack layout's peaking items will remain opaque if inactiveSlideOpacity is set to 1

v3.8.2

• Fix autoplay stop after user interaction (thanks @HelloCore)
• Allow using a custom animated image component with ParallaxImage (thanks @DanielMarkiel)

v3.8.1

• Migrate from deprecated componentWillReceiveProps to componentDidUpdate (thanks @kiarashws)
• Use console.error instead of console.warn for critical warnings (thanks @bardiarastin)
• Update parallax doc (thanks @bardiarastin)

v3.8.0

• Set removeClippedSubviews to false by default for 'tinder' and 'stack' layouts, or when useScrollView is set to true. This aims at preventing a bunch of rendering issues.
• Make sure that autoplay is properly restarted after a touchStart event
• Allow serialized animated event as onScroll. See #439 for more info (thanks @Jberivera)
• Allow using a custom scroll component. See #498 for more info (thanks @martinezguillaume)
• Prevent loop animation from being played when reaching the end of the dataset. See #443 for more info (thanks @suhanmoon)
• Fire the onTouchStart prop. See #464 for more info (thanks @sangle7)
• Add accessibilityLabel to Pagination. See #438 for more info (thanks @thymikee)
• Allow contentContainerCustomStyle to override default paddings. See #482 for more info (thanks @yamov)

v3.7.5

• Fix issue with scrollEnabled introduced in version 3.7.3... again! (thanks @ifsnow)

v3.7.4

• Fix issue with scrollEnabled introduced in version 3.7.3 (thanks @JakeRawr)

v3.7.3

• Fix faulty animated value and make sure to always check for data before checking for data.length
• Fix scrollEnabled override when it was initially set to false (thanks @JakeRawr)

v3.7.2

• Fix ParallaxImage not being rendered (thanks @louiszawadzki)

v3.7.1

• Fix a potential crash in release mode (thanks @hanpanpan200)
• Do not round scroll offset's number in order to prevent potential issues with scroll repositioning

v3.7.0

New features and enhancements

• Add a new callback method: onBeforeSnapToItem()
• Add prop lockScrollTimeoutDuration
• Add the ability to enable/disable callback's execution when snaping programmatically
• Add the ability to change scrollEnabled to true from initially false (thanks @tomauty)

  Bugfixes

• Fix random errors when accessing wrapped component's reference
• Fix errors triggered when calling setState() while the component has already been unmounted

  Other

• Support keyExtractor on ScrollView (thanks @hadimhd)

v3.6.0

• Add a layout prop to let users choose between 3 different carousel layouts (see the documentation)
• Add the ability to define dynamic styles based on scroll position with props scrollInterpolator and slideInterpolatedStyle. This allows implementing custom animations and layouts (see the dedicated documentation).
• Rename props customAnimationType and customAnimationOptions to activeAnimationType and activeAnimationOptions

v3.5.0

• Add the ability to render either a ScrollView component or a FlatList one (default) (see prop useScrollView)
• Add support for versions of React Native < 0.43 (see this note)
• Add support for custom animations (see props customAnimationType and customAnimationOptions)
• Add method triggerRenderingHack() to work around a random FlatList bug that keeps content hidden until the carousel is scrolled
• Hack around ScrollView/FlatList image rendering issues on Android
• Fix issue with tappable dots when loop is enabled

v3.4.0

• Fix snapToItem call that results in snapping to the wrong item when loop is enabled
• Fix issue that, in some use cases, prevents every items but the initial ones to be rendered
• On Android, prevent loop and callback issues because scroll offset's value doesn't return an integer
• Add prop inactiveSlideShift (see #204)
• Expose FlatList's prop inverted (use at your own risk since it will mess with the current handling of RTL layouts)
• Set removeClippedSubviews to true by default

v3.3.4

• Fix issue with possible faulty index when loopClonesPerSide is greater than data length
• Guard against setNativeProps() being undefined
• On Android, make sure that the first item has the proper active style after init
• On iOS, remove the feature "snap as soon as the previous/next item becomes active when lockScrollWhileSnapping is enabled" since it messes with direct calls to snapToItem()

v3.3.3

• Prevent issue on iOS when enableSnap is set to false while lockScrollWhileSnapping is set to true

v3.3.2

• Fix issue with lockScrollWhileSnapping when no callback was provided
• Pagination component: add props activeOpacity and dotContainerStyle

v3.3.1

• Fix issue when initializing the carousel with empty data
• Make tappable PaginationDot snaps to the right item when loop is enabled

v3.3.0

• Bring in the most wanted 'infinite loop' feature :tada: (see the 'Loop' section for more info about the new props loop and loopClonesPerSide)
• Improve Android behavior when momentum is disabled
• Guard against potential errors when component is unmounted
• Add prop lockScrollWhileSnapping to improve behavior when momentum is disabled

v3.2.3

• Fix issue with callback not fired when doing a long swipe

v3.2.2

• Fix RTL issues
• Fix issue with active item when enableMomentum was set to true
• Fix issue with overlapping items (thanks @henninghall)
• ParallaxImage component: allow overriding default styles
• Pagination component: adapt to RTL layouts

v3.2.1

• Fix issue with active item when no callback has been specified (introduced in version 3.2.0)

v3.2.0

• Refactor callback handling. Make sure to use the new prop callbackOffsetMargin if you experience missed callbacks.
• Make item's scale and opacity animations follow scroll value (thanks @hammadj)
• Pagination component: make dots tappable with new props tappableDots and carouselRef (see the example)
• Fix issue when carousel has been unmounted but parent container requires to re-render
• Fix state and scroll issues when the currently active item is being dynamically removed
• Improve snap feeling when momentum is disabled (default)
• Add prop callbackOffsetMargin
• Remove props animationFunc, animationOptions, scrollEndDragDebounceValue, snapOnAndroid, and useNativeOnScroll

v3.1.0

• Pagination component: add new props for advanced customization

v3.0.0

WARNING

• Do not use this version as some temporary code was pushed to npm by mistake. Make sure to use version 3.1.0 instead.

  Breaking changes

• Plugin is now built on top of FlatList, which allows for huge performance optimizations. From now on, items must be rendered using props data and renderItem.

  General

• Add ParallaxImage component (see the specific documentation here)
• Add prop activeSlideAlignment
• Fix issue with autoplay when setting scrollEnabled to false
• Prevent going back to the first item when overscrolling the last one
• Prevent callback from being called at the wrong time in some specific scenarios

v2.4.0

• Add Pagination component (see the specific documentation here)
• Allow firstItem to be changed dynamically
• Allow 0 value for carouselHorizontalPadding and carouselVerticalPadding (thanks @bonbonez)
• Keep the easing of slide's opacity animation linear
• Use native driver for slide's animation (can be overridden via animationOptions)

v2.3.1

• Fix issue when snap is disabled

v2.3.0

• Refactor callback handling to provide a more reliable solution when momentum is disabled
• Fix issue with parallel animations (thanks @jnbt)
• Prevent calls to undefined interpolators when working with dynamic slides (thanks @cskaynar)
• Improve vertical mode
• Add prop scrollEndDragDebounceValue
• Expose current scroll position with this.currentScrollPosition
• Remove props scrollEndDragThrottleValue and snapCallbackDebounceValue (use scrollEndDragDebounceValue instead)

v2.2.2

• Fix issue that prevented inactive styles of first and last items to be applied when using snapToPrev and snapToNext methods

v2.2.1

• Do not mark sliderWidth and sliderHeight as required
• Add warnings when properties specific to carousel's orientation haven't been set

v2.2.0

• Implement vertical mode (prop vertical)
• Make sure that current active item is properly updated when snapping
• Prevent issues when 'sliderWidth' is smaller than viewport's width
• Recalculate card positions on layout to handle rotation (thanks @andrewpope); make sure to read this note
• Refresh card positions if slider and/or item's dimensions are updated (thanks @hoangnm)
• Add props scrollEndDragThrottleValue and snapCallbackDebounceValue
• Expose View's onLayout prop
• Deprecate prop onScrollViewScroll

v2.1.4

• Add prop onScrollViewScroll

v2.1.3

• Default value for showsHorizontalScrollIndicator is now false
• Expose ScrollView's onSscroll prop (thanks @radko93)

v2.1.2

• Do not trigger onSnapToItem when snapping back to the same slide (thanks @rgabs)
• Add prop carouselHorizontalPadding to override container's inner padding (thanks @skeie)

v2.1.1

• Ensure compatibility with RN 0.43 (previous version of plugin's dependency react-addons-shallow-compare was breaking with React 16)
• Fix issue with padding on iOS that could cause the carousel to snap back when its last item was clicked

v2.1.0

• Add RTL support
• Keep current active item when adding slides dynamically
• Prevent invalid firstItem number
• Add prop activeSlideOffset

v2.0.3

• Prevent error when carousel has only one child (thanks @kevinvandijk)
• Fix issue when appending dynamic slides (the first one was ignored)
• Fix edge case that prevented the first slide from being focused when swiping back with momentum enabled
• Bump example's RN version to 0.42.3

v2.0.2

• Make sure that scroll indicator is hidden by default

v2.0.1

• Fix un-handled exception with interpolators (thanks @chitezh)

v2.0.0

• Items are now direct children of the <Carousel /> component, which makes it easier to use (thanks @Jonarod)
• Props items and renderItem have been removed

v1.6.1

• Due to some touch events being buggy, rework methods so the children will receive touch events on Android

v1.6.0

• Add prop enableMomentum
• Fix an infinite-loop on iOS with momentum enabled
• Fix the snapping effect when releasing touch without interia on iOS with momentum enabled
• Fix autoplay on Android, it should start and stop properly and stop being triggered while swiping
• Use View.propTypes.style instead of PropTypes.number in styles validation (thanks @pesakitan22)

v1.5.0

• Items length can now be changed on-the-fly (thanks @superical)
• Now handling momentum (thanks @FakeYou)

v1.4.0

• Better update strategy with shallowCompare
• Add snapToNext(), snapToPrev(), currentIndex methods and properties

v1.3.1

• Properly center on first item when mounting component on Android (potentially iOS too)

v1.3.0

• Pass the item data as the 2nd param of onSnapToItem callback

v1.2.1

• Fix reference call when the component has been unmounted

v1.2.0

• Add prop onSnapToItem

v1.1.0

• Center slides properly
• Handle one slide only
• Add props inactiveSlideScale, inactiveSlideOpacity, containerCustomStyle and contentContainerCustomStyle