Skip to content

r0b0t3d/react-native-carousel

Repository files navigation

react-native-carousel

Hits

alt text

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 react-native-reanimated@2.1.0

Show cases

Loop Scale Alignment
alt text alt text alt text

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