react-native-carousel

Getting started

$ yarn add @r0b0t3d/react-native-carousel

Note: Currently, I am using react-native-reanimated for animation. So you should install it as well

$ yarn add react-native-reanimated

Breaking changes

v3.4.0

Added:

• You have to wrap your component inside withCarouselContext
• useCarouselContext hook

Removed:

• Remove component's ref

Changed:

• Methods goNext, goPrev, snapToItem now accessible via useCarouselContext

const {
    goNext,
    goPrev,
    snapToItem
  } = useCarouselContext();

Other versions

v3.3.0

• Changed: renderItem now required and add more props to easy customization

renderItem: (
  data: { item: T; index?: number },
  animatedData?: { scrollPosition?: Animated.SharedValue<number>, offset?: number }
) => React.ReactNode

v3.0.0

• Added:
  • animatedPage: animated value used which is current selected page. Used to pass into the PaginationIndicator for animation.
• Removed:
  • useIndicator, indicatorContainerStyle, renderIndicator, . Used PaginationIndicator instead
  • renderOverlay: you can render overlay inside renderItem function
• Changed:
  • renderImage -> renderItem

v2.0.0

• requires [email protected]

Show cases

Loop	Scale	Alignment

Loop

<Carousel
  loop={true}
  autoPlay={true}
  duration={3000}
  animation="parallax"
/>

Scale

<Carousel
  itemWidth={width - 100}
  inactiveOpacity={0.5}
  inactiveScale={0.9}
/>

Alignment

<Carousel
  itemWidth={width - 100}
  inactiveOpacity={0.5}
  inactiveScale={0.9}
  firstItemAlignment="start"
/>

Usage

import Carousel, {
  withCarouselContext,
  useCarouselContext,
} from '@r0b0t3d/react-native-carousel';

function MyCarousel() {
  const {
    goNext,
    goPrev,
    snapToItem
  } = useCarouselContext(); // <- use this instead of passing ref to Carousel

  return (
    <View>
      <Carousel
        style={{ height: 200 }}
        data={data}
        loop={false}
        autoPlay={true}
        duration={3000}
        itemWidth={width - 100}
        inactiveOpacity={0.5}
        inactiveScale={0.9}
        firstItemAlignment="start"
        spaceBetween={20}
        animatedPage={currentPage}
        renderItem={({item}) => {
          return (
            <Image
              style={{
                flex: 1,
                backgroundColor: 'red',
              }}
              source={{ uri: item.url }}
            />
          );
        }}
      />
      <View>
        <PaginationIndicator
          containerStyle={{ marginTop: 20 }}
          activeIndicatorStyle={{
            height: 10,
            borderRadius: 5,
          }}
          indicatorConfigs={{
            spaceBetween: 10,
            indicatorWidth: 10,
            indicatorSelectedWidth: 20,
          }}
        />
      </View>
    </View>
  );
}

export default withCarouselContext(MyCarousel) // <-- To use carousel context, you need wrap your component with withCarouselContext

Carousel

Properties

Props	Description	Default
data	Array of item to be rendered. - id: string: this will be used as key to render - source: ImageSourcePropType: optional. Image source. If you don't want to pass source here. You could use renderItem below to render your custom image. ------ Or it could be array of string
loop?	Whether your carousel can loop or not	false
initialPage?	Set the first page show up	0
additionalPagesPerSide?	When looping, how many page will be added at head and tail to perform loop effect	2
autoPlay?	Auto animate to next image with duration.	false
duration?	Duration to animate. used with autoPlay above	1000
animation?	Predefined animation. Will be parallax for now
sliderWidth?	Define slider width	screen's width
itemWidth?	Define item width	screen's width
firstItemAlignment?	`'center'	'start'` Align first item
inactiveOpacity?	[0 - 1] Define opacity for inactive items	1
inactiveScale?	[0 - 1] define scale value for inactive items	1
spaceBetween?	Add additional space between items	0
spaceHeadTail?	Add more space in head/tail. This only work if firstItemAlignment = 'start'	0
animatedPage?	Animated value which is the current page. This value used to pass into PaginationIndicator for animation
renderItem	(data: { item: T; index?: number }, animatedData?: { scrollPosition?: Animated.SharedValue<number>, offset?: number }) => React.ReactNode Render carousel item
onPageChange?	(index: number) => void Callback to notify when page change

Methods

Method	Description
goNext	Go to next index
goPrev	Go to previous index
snapToItem	(index: number, animated?: boolean) => void Snap to specific index - index: destination index - animated: should animate or not, default is true

withCarouselContext

This HOC provides easy way to wrap your component with CarouselContext.Provider. So if you'd like to use useCarouselContext, you need to wrap your component with this.

PaginationIndicator

Easy way to define the indicator for your carousel.

Please note that, this component only works with withCarouselContext. So please make sure that it is rendered under the component that you wrap with withCarouselContext

Check example above for more info

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT