Carousel

Installation

$ npx shadcn@latest add https://goodui.dev/native/r/carousel.json

Then run npx expo install --fix so react-native-gesture-handler, react-native-reanimated match your Expo SDK. Files land in components/goodui-native/carousel.

Usage

import { View } from "react-native";
import { Carousel, CarouselParallax } from "@/components/goodui-native/carousel/carousel";
import { Text } from "@/components/goodui-native/foundation/text";

type Stay = { id: string; title: string; price: string };

export function FeaturedStays({ stays, open }: { stays: Stay[]; open: (s: Stay) => void }) {
  return (
    <Carousel
      data={stays}
      height={200}
      keyExtractor={(s) => s.id}
      getItemLabel={(s) => s.title}
      accessibilityLabel="Featured stays"
      onItemPress={(s) => open(s)}
      renderItem={({ item }) => (
        <View style={{ flex: 1, justifyContent: "flex-end", padding: 16 }}>
          <Text size="title3" weight="medium">{item.title}</Text>
          <Text tone="secondary">{item.price} a night</Text>
        </View>
      )}
    />
  );
}

When to use

Examples

<Carousel
  data={offers}
  autoplay={5000}
  height={180}
  renderItem={({ item }) => (
    <>
      <CarouselParallax>
        <Image source={item.image} style={{ flex: 1 }} />
      </CarouselParallax>
      <Text style={{ margin: 16 }}>{item.title}</Text>
    </>
  )}
/>

const [step, setStep] = useState(0);

<Carousel data={steps} index={step} onIndexChange={setStep} itemWidth={1} gap={0} variant="flat" renderItem={...} />

API reference

Motion and haptics

• •Cards follow the finger 1:1 and settle on the smooth spring with the release velocity; a fling moves one card at most.
• •Past the first or last card the drag meets growing resistance.
• •variant='scale' shrinks neighbours to 0.9 and dims them as they leave the center, continuously with the drag.
• •The pagination pill stretches from the old card to the new one with the drag; with autoplay the active pill fills over the interval.
• •CarouselParallax layers lag behind their card by a fraction of its width.
• •Reduced motion: release settles on a short timing curve, programmatic changes jump, parallax stays still and autoplay is off.

• •Haptic: select when a swipe, a tap on a neighbour or a pill changes the card (configurable with the haptic prop); none for autoplay

• •Position, scale, dimming, pills and parallax run on the UI thread from one shared value; React renders only when the centered card changes.
• •Every card is rendered: keep it to a few dozen cards.

Accessibility

• •The carousel is one adjustable element: swipe up or down with a screen reader to move between cards.
• •Its value reads '2 of 5' plus getItemLabel for the centered card; with onItemPress, activating it presses that card.
• •Every pagination pill is a button labelled 'Go to card n' with a 44 pt tall touch target.
• •Autoplay is off under reduced motion and pauses while a finger or pointer rests on the cards.
• •On the web it is a focusable slider with aria-valuenow (card number) and aria-valuetext; arrow keys move between cards and Enter presses the centered card.

Notes for AI

Related