## Common Props

| name                    | required                  | default                                                                                               | types                                                                                                                    | description                                                                                                                    |
| ----------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| data                    | ✅                        |                                                                                                       | T[]                                                                                                                      | Carousel items data set                                                                                                        |
| renderItem              | ✅                        |                                                                                                       | (info: { item: T, index: number, animationValue: SharedValue\<number> }) => React.ReactElement                           | Render carousel item                                                                                                           |
| defaultScrollOffsetValue| ❌                        | useSharedValue<number>(0)                                                                                                  | boolean                                                                                             | The default animated value of the carousel.             |
| autoFillData            | ❌                        | true                                                                                                  | boolean                                                                                                                  | Auto fill data array to allow loop playback when the loop props is true.([1] => [1, 1, 1]；[1, 2] => [1, 2, 1, 2])             |
| vertical                | ❌                        | false                                                                                                 | boolean                                                                                                                  | Layout items vertically instead of horizontally                                                                                |
| width                   | vertical ❌ horizontal ✅ | '100%'                                                                                                | number \| undefined                                                                                                      | Specified carousel item width                                                                                                  |
| height                  | vertical ✅ horizontal ❌ | '100%'                                                                                                | number \| undefined                                                                                                      | Specified carousel item height                                                                                                 |
| mode                    | ❌                        | default                                                                                               | 'horizontal-stack'\|'vertical-stack'\|'parallax'                                                                         | Carousel Animated transitions                                                                                                  |
| modeConfig              | ❌                        |                                                                                                       |                                                                                                                          | Different modes correspond to different configurations. For details, see below[modeConfig](#`modeConfig` Props)                |
| style                   | ❌                        | {}                                                                                                    | ViewStyle                                                                                                                | Carousel container style                                                                                                       |
| defaultIndex            | ❌                        | 0                                                                                                     | number                                                                                                                   | Default index                                                                                                                  |
| autoPlay                | ❌                        | false                                                                                                 | boolean                                                                                                                  | Auto play                                                                                                                      |
| autoPlayReverse         | ❌                        | false                                                                                                 | boolean                                                                                                                  | Auto play reverse playback                                                                                                     |
| autoPlayInterval        | ❌                        | 1000                                                                                                  | number                                                                                                                   | Auto play playback interval                                                                                                    |
| scrollAnimationDuration | ❌                        | 500                                                                                                   | number                                                                                                                   | Time a scroll animation takes to finish                                                                                        |
| loop                    | ❌                        | true                                                                                                  | boolean                                                                                                                  | Carousel loop playback                                                                                                         |
| testID                  | ❌                        |                                                                                                       | string                                                                                                                   | Used to locate this view in end-to-end tests                                                                                   |
| onSnapToItem            | ❌                        |                                                                                                       | (index: number) => void                                                                                                  | Callback fired when navigating to an item                                                                                      |
| onScrollBegin           | ❌                        |                                                                                                       | () => void                                                                                                               | Callback fired when scroll begin                                                                                               |
| onScrollEnd             | ❌                        |                                                                                                       | (index: number) => void                                                                                                  | Callback fired when scroll end                                                                                                 |
| withAnimation           | ❌                        |                                                                                                       | {type: 'spring';config: WithSpringConfig;} \| {type: 'timing';config: WithTimingConfig;}                                 | Specifies the scrolling animation effect                                                                                       |
| panGestureHandlerProps  | ❌                        | {}                                                                                                    | Omit<Partial\<PanGestureHandlerProps\>,'onHandlerStateChange'>                                                           | PanGestureHandler props                                                                                                        |
| windowSize              | ❌                        | 0                                                                                                     | number                                                                                                                   | The maximum number of items that can respond to pan gesture events, `0` means all items will respond to pan gesture events     |
| onProgressChange        | ❌                        |                                                                                                       | onProgressChange?: (offsetProgress: number,absoluteProgress: number) => void                                             | On progress change. `offsetProgress`:Total of offset distance (0 390 780 ...); `absoluteProgress`:Convert to index (0 1 2 ...) |
| modeConfig              | ❌                        | { snapDirection: 'left',moveSize: window.width,stackInterval: 30,scaleInterval: 0.08,rotateZDeg: 135} | {moveSize?: number;stackInterval?: number;scaleInterval?: number;rotateZDeg?: number;snapDirection?: 'left' \| 'right';} | Stack layout animation style                                                                                                   |
| pagingEnabled           | ❌                        | true                                                                                                  | boolean                                                                                                                  | When true, the scroll view stops on multiples of the scroll view's size when scrolling                                         |
| overscrollEnabled       | ❌                        | true                                                                                                  | boolean                                                                                                                  | If enabled, the item will scroll to the first placement when scrolling past the edge rather than closing to the last. (previous conditions: loop=false)                                         |
| snapEnabled             | ❌                        | true                                                                                                  | boolean                                                                                                                  | If enabled, releasing the touch will scroll to the nearest item, valid when pagingEnabled=false                                |
| enabled                 | ❌                        | true                                                                                                  | boolean                                                                                                                  | when false, Carousel will not respond to any gestures                                                                          |
| customConfig            | ❌                        |                                                                                                       | () => {type?: 'negative' \| 'positive';viewCount?: number;}                                                              | Custom carousel config                                                                                                         |
| customAnimation         | ❌                        |                                                                                                       | (value: number) => Animated.AnimatedStyleProp<ViewStyle>                                                                 | Custom animations. For details, see below[custom animation](./custom-animation.md)                                             |
| maxScrollDistancePerSwipe | ❌                        |                                                                                              | number                                                                                                                   | Maximum offset value for one scroll. If `props.vertical = true`, this will be `maxScrollDistancePerSwipeY`. If `props.vertical = false`, this will be `maxScrollDistancePerSwipeX`. |

## `modeConfig` Props

### Parallax

| name                      | required | default                                                            | types  | description                          |
| ------------------------- | -------- | ------------------------------------------------------------------ | ------ | ------------------------------------ |
| parallaxScrollingOffset   | ❌       | 100                                                                | number | control prev/next item offset        |
| parallaxScrollingScale    | ❌       | 0.8                                                                | number | control prev/current/next item scale |
| parallaxAdjacentItemScale | ❌       | parallaxAdjacentItemScale \|\| Math.pow(parallaxScrollingScale, 2) | number | control prev/next item scale         |

### Stack

| name            | required | default       | types           | description              |
| --------------- | -------- | ------------- | --------------- | ------------------------ |
| showLength      | ❌       | data.length-1 | number          | Display number           |
| moveSize        | ❌       | screen.width  | number          | Item translate size      |
| stackInterval   | ❌       | 18            | number          | The spacing of each item |
| scaleInterval   | ❌       | 0.04          | number          | The scale of each item   |
| opacityInterval | ❌       | 0.1           | number          | The opacity of each item |
| rotateZDeg      | ❌       | 30            | number          | The item rotation Angle  |
| snapDirection   | ❌       | 'left'        | 'left'\|'right' | Slide direction          |

## Ref

| name            | types                                                                                  | description                                                                                                                                                                                                                                              |
| --------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| prev            | ({ count: number, animated: boolean, onFinished?: () => void }) => void                | Scroll to previous item, it takes one optional argument (count), which allows you to specify how many items to cross                                                                                                                                     |
| next            | ({ count: number, animated: boolean, onFinished?: () => void }) => void                | Scroll to next item, it takes one optional argument (count), which allows you to specify how many items to cross                                                                                                                                         |
| scrollTo        | ({ index: number, count: number, animated: boolean, onFinished?: () => void }) => void | Use count to scroll to a position where relative to the current position, scrollTo({count:-2}) is equivalent to prev(2), scrollTo({count:2}) is equivalent to next(2). And also can jump to specific position, e.g. scrollTo({index:2,animated:false}) |
| getCurrentIndex | ()=>number                                                                             | Get current item index                                                                                                                                                                                                                                   |