# React Native Carousel & Pager

> A React Native carousel and pager for iOS, Android and the web with no native code: swipe between pages, peek at the next slide, dots that follow the finger, loop, autoplay that pauses on touch and respects reduce motion, and arrow keys on the web. Replaces react-native-pager-view and react-native-reanimated-carousel.

# Carousel & Pager

`Pager` shows full-size pages you swipe between: onboarding, a photo gallery, swipeable tabs. `Carousel` is the same paging scroll view with dots, arrows on the web, slides narrower than the screen so the next one peeks in, loop and autoplay. Both swipe natively on iOS and Android and snap with CSS scroll snapping on the web, with no native module and no Reanimated.

```tsx
import { Carousel, PageIndicator, Pager } from 'patine-ui';
```

```tsx live
import { View } from 'react-native';
import { Carousel, Text } from 'patine-ui';

const slides = [
  { title: 'Plan', color: '#6366F1' },
  { title: 'Pack', color: '#0EA5E9' },
  { title: 'Go', color: '#10B981' },
];

export default function Example() {
  return (
    <Carousel itemWidth="85%" accessibilityLabel="Trip steps" style={{ width: 340 }}>
      {slides.map((slide) => (
        <View key={slide.title} style={{ height: 160, borderRadius: 16, backgroundColor: slide.color, alignItems: 'center', justifyContent: 'center' }}>
          <Text size="2xl" weight="semibold" style={{ color: 'white' }}>{slide.title}</Text>
        </View>
      ))}
    </Carousel>
  );
}
```

## Example: a product gallery

A product page: swipe the photos, or press a thumbnail to jump to one. The thumbnails and the counter follow the carousel's `value`.

```tsx live
import { useState } from 'react';
import { Image, Pressable } from 'react-native';
import { Carousel, HStack, Text, VStack } from 'patine-ui';

const PHOTOS = [
  { id: 21, alt: 'The sneaker from the side' },
  { id: 26, alt: 'The sneaker from above' },
  { id: 103, alt: 'The sneaker worn outdoors' },
  { id: 177, alt: 'The sole' },
];
const url = (id: number, w: number, h: number) => `https://picsum.photos/id/${id}/${w}/${h}`;

export default function Example() {
  const [index, setIndex] = useState(0);
  return (
    <VStack gap="sm" style={{ width: '100%', maxWidth: 380 }}>
      <Carousel value={index} onValueChange={setIndex} labels={PHOTOS.map((p) => p.alt)} accessibilityLabel="Product photos">
        {PHOTOS.map((p) => (
          <Image key={p.id} source={{ uri: url(p.id, 760, 560) }} style={{ height: 260, borderRadius: 16 }} accessibilityLabel={p.alt} />
        ))}
      </Carousel>
      <HStack justify="space-between" align="center">
        <HStack gap="xs">
          {PHOTOS.map((p, i) => (
            <Pressable key={p.id} onPress={() => setIndex(i)} accessibilityRole="button" accessibilityLabel={`Show ${p.alt.toLowerCase()}`} accessibilityState={{ selected: i === index }}>
              <Image source={{ uri: url(p.id, 96, 96) }} style={{ width: 44, height: 44, borderRadius: 8, opacity: i === index ? 1 : 0.5 }} />
            </Pressable>
          ))}
        </HStack>
        <Text size="sm" color="textSecondary">
          {index + 1} / {PHOTOS.length}
        </Text>
      </HStack>
    </VStack>
  );
}
```

## Pager

Give the Pager a height (`style={{ flex: 1 }}` in a screen) and one child per page. Pair it with `PageIndicator` for dots wherever you want them, or set `showIndicator`.

```tsx live
import { useState } from 'react';
import { Button, Heading, PageIndicator, Pager, Text, VStack } from 'patine-ui';

const pages = [
  { title: 'Welcome', body: 'Everything you need in one place.' },
  { title: 'Stay in sync', body: 'Your data follows you to every device.' },
  { title: 'You are all set', body: 'Start by creating your first project.' },
];

export default function Example() {
  const [page, setPage] = useState(0);
  return (
    <VStack gap="md" style={{ width: 320 }}>
      <Pager value={page} onValueChange={setPage} accessibilityLabel="Welcome tour" style={{ height: 140 }}>
        {pages.map((p) => (
          <VStack key={p.title} gap="sm" style={{ flex: 1, padding: 16, justifyContent: 'center' }}>
            <Heading level={3}>{p.title}</Heading>
            <Text color="textSecondary">{p.body}</Text>
          </VStack>
        ))}
      </Pager>
      <PageIndicator count={pages.length} value={page} onValueChange={setPage} />
      <Button onPress={() => setPage(Math.min(page + 1, pages.length - 1))}>Next</Button>
    </VStack>
  );
}
```

Changing `value` scrolls to that page without calling `onValueChange`; it fires only when a page settles after a swipe, an arrow, a dot, a key or autoplay.

## Loop and autoplay

`loop` goes from the last slide on to the first. `autoplay` moves on every 4 seconds, or pass a number of milliseconds. It pauses while the carousel is touched, hovered or has focus, and it never runs when the OS asks to reduce motion.

```tsx live
import { View } from 'react-native';
import { Carousel, Text } from 'patine-ui';

export default function Example() {
  return (
    <Carousel loop autoplay={3000} accessibilityLabel="Offers" style={{ width: 320 }}>
      {['20% off shoes', 'Free delivery', 'New arrivals'].map((offer, i) => (
        <View key={offer} style={{ height: 120, borderRadius: 12, backgroundColor: ['#F59E0B', '#EF4444', '#8B5CF6'][i], alignItems: 'center', justifyContent: 'center' }}>
          <Text size="lg" weight="semibold" style={{ color: 'white' }}>{offer}</Text>
        </View>
      ))}
    </Carousel>
  );
}
```

## Designs

| | Dots | Arrows |
| --- | --- | --- |
| `brand` | A primary pill sliding over soft dots | Round, outlined |
| `ios` | UIPageControl's 7pt dots, the current one solid | Round, filled |
| `material` | 8dp dots, the current one a primary pill | Round, tonal |
| `web` | 8px dots, the current one primary | Round, outlined |

## Accessibility

- The carousel is a `region`; name it with `accessibilityLabel`. On the web each slide is a group named "Slide 2 of 5" (`labels.slide`).
- On the web, focus the carousel and use the arrow keys, Home and End. The arrows are buttons named "Previous slide" and "Next slide".
- On iOS and Android the dots are one adjustable control: screen-reader users swipe up or down to change the slide, and hear "Slide 2 of 5".
- Loop copies are hidden from screen readers. Autoplay pauses on touch, hover and focus, and is off with reduce motion.

## Props

### Carousel

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | — | One slide per child. |
| `value` | `number` | — | The slide shown, from 0. |
| `defaultValue` | `number` | `0` | The first slide when uncontrolled. |
| `onValueChange` | `(index: number) => void` | — | A slide settles after a swipe, arrow, dot, key or autoplay. |
| `itemWidth` | `number \| string` | `'100%'` | Points, or a percentage like `'80%'`. Under 100% shows the next slide peeking in. |
| `align` | `'center' \| 'start'` | `'center'` | Where a narrower slide rests. |
| `gap` | `number` | theme `md` spacing | Space between slides. |
| `loop` | `boolean` | `false` | Wrap from the last slide to the first. |
| `autoplay` | `boolean \| number` | `false` | `true` is every 4000 ms. |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Vertical needs a height. |
| `scrollEnabled` | `boolean` | `true` | Swiping; arrows, dots and keys still work. |
| `showIndicator` | `boolean` | `true` | Dots under the slides. |
| `showArrows` | `boolean` | on the web | Previous and next buttons. |
| `accessibilityLabel` | `string` | — | Names the region. |
| `labels` | `Partial<CarouselLabels>` | English | `previous`, `next`, and `slide` with `{page}` and `{count}`. |
| `style` / `styles` | | — | `styles` slots: `container`, `item`, `indicator`, `arrow`. |
| `theme` / `design` | | provider's | |

### Pager

The same props as Carousel except `itemWidth`, `align`, `loop` and `autoplay`, with `gap` `0`, `showIndicator` `false` and `showArrows` `false` by default.

### PageIndicator

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `count` | `number` | — | Number of pages. |
| `value` | `number` | — | The current page, from 0. |
| `onValueChange` | `(index: number) => void` | — | A dot is tapped or a screen reader steps. Leave it out for dots that only show the page. |
| `label` | `string` | `'Slide {page} of {count}'` | Read with the page. |
| `theme` / `design` | | provider's | |
