Carousel displays its children as carousel items which can be scrolled. You can control how many items are visible in the scrollable area at the same time with the visibleItems property. If it's not passed, the width of the items will be defined by the width of the passed children.
<Carousel visibleItems={2}>
<View backgroundColor="neutral-faded" height={25} />
<View backgroundColor="neutral-faded" height={25} />
<View backgroundColor="neutral-faded" height={25} />
<View backgroundColor="neutral-faded" height={25} />
<View backgroundColor="neutral-faded" height={25} />
<View backgroundColor="neutral-faded" height={25} />
</Carousel>You can control the spacing between items with the gap property, which defines the multiplier of the base unit token value. This way, you can align items in the Carousel with your product grid.
<Carousel visibleItems={3} gap={8}>
<View backgroundColor="neutral-faded" height={25} />
<View backgroundColor="neutral-faded" height={25} />
<View backgroundColor="neutral-faded" height={25} />
<View backgroundColor="neutral-faded" height={25} />
<View backgroundColor="neutral-faded" height={25} />
<View backgroundColor="neutral-faded" height={25} />
</Carousel>You can make the Carousel full-width with the bleed property. It will apply negative margin to the carousel while keeping the items aligned with the rest of the content.
<Carousel visibleItems={3} gap={4} bleed={4}>
<View backgroundColor="neutral-faded" height={25} />
<View backgroundColor="neutral-faded" height={25} />
<View backgroundColor="neutral-faded" height={25} />
<View backgroundColor="neutral-faded" height={25} />
<View backgroundColor="neutral-faded" height={25} />
<View backgroundColor="neutral-faded" height={25} />
</Carousel>Carousel provides access to its navigateBack and navigateForward methods through an instanceRef property. If you create a React ref and pass it to Carousel, you can navigate the Carousel imperatively.
For example, you can scroll the Carousel with a time interval or control it with buttons rendered outside of the component. In this case, it might be useful to set the navigationDisplay property to hidden to hide the original navigation controls.
function Component() {
const carouselRef = React.useRef<CarouselInstance | null>(null);
return (
<View gap={3}>
<View direction="row" gap={2} align="center">
<View.Item grow>
<Text variant="featured-3" weight="bold">
Carousel title
</Text>
</View.Item>
<Button onClick={() => carouselRef.current?.navigateBack()}>
Back
</Button>
<Button onClick={() => carouselRef.current?.navigateForward()}>
Forward
</Button>
</View>
<Carousel
visibleItems={3}
instanceRef={carouselRef}
navigationDisplay="hidden"
>
<View backgroundColor="neutral-faded" height={25} />
<View backgroundColor="neutral-faded" height={25} />
<View backgroundColor="neutral-faded" height={25} />
<View backgroundColor="neutral-faded" height={25} />
<View backgroundColor="neutral-faded" height={25} />
<View backgroundColor="neutral-faded" height={25} />
</Carousel>
</View>
);
Carousel supports responsive syntax for the bleed, gap and visibleItems properties. Use object syntax to control their value based on the viewport size. Responsive properties are mobile-first, so selecting a value for a viewport will also apply it to all wider viewports.
For example, this Carousel uses x4 bleed on small and medium screens but renders normally on large and extra-large screens.
<Carousel bleed={{ s: 4, l: 0 }} />