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.
import { Carousel, PageIndicator, Pager } from 'patine-ui';
<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>
Try the props
itemWidthalign<Carousel accessibilityLabel="Featured">
…
</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.
<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.
<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.
<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 withaccessibilityLabel. 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 |