Carousel

A scrollable carousel component with navigation controls for cycling through content.

The Carousel component provides a scrollable container with navigation arrows for cycling through slides. It supports horizontal and vertical orientations, auto-sizing based on item dimensions, and exposes a CarouselApi for programmatic control.

Preview

Installation

npx novaui-cli add carousel

Import

import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselPrevious,
  CarouselNext,
} from 'novaui-components'

Basic Usage

import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselPrevious,
  CarouselNext,
} from 'novaui-components'
import { View, Text } from 'react-native'

export function BasicCarousel() {
  return (
    <Carousel className="w-full max-w-xs">
      <CarouselContent>
        {[1, 2, 3, 4, 5].map((item) => (
          <CarouselItem key={item}>
            <View className="p-1">
              <View className="rounded-md border border-border bg-muted p-6 items-center justify-center">
                <Text className="text-3xl font-semibold text-foreground">
                  {item}
                </Text>
              </View>
            </View>
          </CarouselItem>
        ))}
      </CarouselContent>
      <CarouselPrevious />
      <CarouselNext />
    </Carousel>
  )
}

Vertical Orientation

<Carousel orientation="vertical" className="w-full max-w-xs">
  <CarouselContent>
    {[1, 2, 3].map((item) => (
      <CarouselItem key={item}>
        <View className="p-1">
          <View className="rounded-md border border-border bg-muted p-6 items-center justify-center">
            <Text className="text-3xl font-semibold">{item}</Text>
          </View>
        </View>
      </CarouselItem>
    ))}
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>

With API Control

Use the setApi callback for programmatic carousel control:

import { useState } from 'react'
import { type CarouselApi } from 'novaui-components'

export function ControlledCarousel() {
  const [api, setApi] = useState<CarouselApi>()

  return (
    <View className="gap-4">
      <Carousel setApi={setApi}>
        <CarouselContent>
          {[1, 2, 3].map((item) => (
            <CarouselItem key={item}>
              <View className="rounded-md border border-border bg-muted p-6 items-center justify-center">
                <Text className="text-3xl font-semibold">{item}</Text>
              </View>
            </CarouselItem>
          ))}
        </CarouselContent>
      </Carousel>
      <View className="flex-row gap-2">
        <Button label="Prev" onPress={() => api?.scrollPrev()} />
        <Button label="Next" onPress={() => api?.scrollNext()} />
      </View>
    </View>
  )
}

Props API

Carousel

Extends React.ComponentPropsWithoutRef<typeof View>:

Prop	Type	Default	Description
`orientation`	`'horizontal' \| 'vertical'`	`'horizontal'`	Scroll direction
`setApi`	`(api: CarouselApi) => void`	-	Callback to receive the carousel API
`className`	`string`	-	Additional CSS classes

CarouselApi

Method	Type	Description
`scrollPrev`	`() => void`	Scroll to the previous slide
`scrollNext`	`() => void`	Scroll to the next slide
`scrollTo`	`(index: number) => void`	Scroll to a specific slide
`canScrollPrev`	`boolean`	Whether there is a previous slide
`canScrollNext`	`boolean`	Whether there is a next slide

CarouselContent

Extends React.ComponentPropsWithoutRef<typeof View>:

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes

CarouselItem

Extends React.ComponentPropsWithoutRef<typeof View>:

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes

CarouselPrevious / CarouselNext

Extends Button props:

Prop	Type	Default	Description
`variant`	`string`	`'outline'`	Button variant
`size`	`string`	`'icon'`	Button size
`className`	`string`	-	Additional CSS classes

Best Practices

Provide navigation: Always include CarouselPrevious and CarouselNext or a programmatic control
Keep slides consistent: Use the same height and layout for all carousel items
Limit slide count: Avoid too many slides — consider pagination for large datasets
Indicate position: Show slide indicators or counts so users know their position
Use appropriate orientation: Vertical carousels work well for card stacks and galleries

Scroll Area - For generic scrollable containers
Tabs - For tabbed content switching

Continue reading

Getting Started Components Overview Popular: Dialog SEO Playbook

Carousel

Continue reading

On this page