Skip to main content

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';
Behaves like
Loading…
<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​

Behaves like
Props
itemWidth
align
<Carousel accessibilityLabel="Featured">
…
</Carousel>

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

Behaves like
Loading…
<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.

Loading…
<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.

Behaves like
Loading…
<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​

DotsArrows
brandA primary pill sliding over soft dotsRound, outlined
iosUIPageControl's 7pt dots, the current one solidRound, filled
material8dp dots, the current one a primary pillRound, tonal
web8px dots, the current one primaryRound, 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​

PropTypeDefaultDescription
childrenReactNode—One slide per child.
valuenumber—The slide shown, from 0.
defaultValuenumber0The first slide when uncontrolled.
onValueChange(index: number) => void—A slide settles after a swipe, arrow, dot, key or autoplay.
itemWidthnumber | 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.
gapnumbertheme md spacingSpace between slides.
loopbooleanfalseWrap from the last slide to the first.
autoplayboolean | numberfalsetrue is every 4000 ms.
orientation'horizontal' | 'vertical''horizontal'Vertical needs a height.
scrollEnabledbooleantrueSwiping; arrows, dots and keys still work.
showIndicatorbooleantrueDots under the slides.
showArrowsbooleanon the webPrevious and next buttons.
accessibilityLabelstring—Names the region.
labelsPartial<CarouselLabels>Englishprevious, next, and slide with {page} and {count}.
style / styles—styles slots: container, item, indicator, arrow.
theme / designprovider's

Pager​

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

PageIndicator​

PropTypeDefaultDescription
countnumber—Number of pages.
valuenumber—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.
labelstring'Slide {page} of {count}'Read with the page.
theme / designprovider's