Pallas UI
DocsComponents
Core Concepts
    • Introduction
    • Getting Started
    • Theming
    • Color Tokens
    • Spacing & Sizing
    • Layout Guide
    • AspectRatio
    • Box
    • Flex
    • Grid
    • Shapes
Previews
    • Accordion
    • Alert
    • Avatar
    • Badge
    • Breadcrumb
    • Button
    • Carousel
    • Checkbox
    • Combobox
    • Command
    • Date Picker
    • Form
    • Input
    • Input OTP
    • Label
    • MenuBar
    • Modal
    • Popover
    • Progress
    • Radio Group
    • Segmented
    • Select
    • Separator
    • Sheet
    • Sidebar
    • Skeleton
    • Slider
    • Spinner
    • Steps
    • Switch
    • Tabs
    • Textarea
    • Toast
    • Tooltip
    • Typography
  1. Components
  2. Carousel

Carousel

A flexible and accessible carousel component for displaying content in a scrollable container.

Slide 1
Slide 2
Slide 3
Slide 4

Installation

Install the following dependencies

npm install @pallas-ui/carousel

Copy and paste the following code into your project

'use client'
import * as CarouselPrimitive from '@pallas-ui/carousel'
import { type Assign, type WithFixedClassName, createStyleContext } from '@pallas-ui/style-context'
import { cx } from '@styled-system/css'
import { type CarouselVariantProps, button, carousel } from '@styled-system/recipes'
import type { ComponentProps, JsxStyleProps } from '@styled-system/types'
import * as React from 'react'
import type { ButtonProps } from '../button'
 
const { withProvider, withContext } = createStyleContext(carousel)
 
export type RootProps = Assign<
  WithFixedClassName<CarouselPrimitive.CarouselRootProps>,
  JsxStyleProps & CarouselVariantProps
>
 
export type PreviousProps = Assign<
  ComponentProps<typeof CarouselPrimitive.Previous>,
  JsxStyleProps & ButtonProps
>
 
export type NextProps = Assign<
  ComponentProps<typeof CarouselPrimitive.Next>,
  JsxStyleProps & ButtonProps
>
 
export const Root = withProvider<React.ComponentRef<typeof CarouselPrimitive.Root>, RootProps>(
  CarouselPrimitive.Root,
  'root',
)
 
export const List = withContext<
  React.ComponentRef<typeof CarouselPrimitive.List>,
  Assign<ComponentProps<typeof CarouselPrimitive.List>, JsxStyleProps>
>(CarouselPrimitive.List, 'list')
 
export const Item = withContext<
  React.ComponentRef<typeof CarouselPrimitive.Item>,
  Assign<ComponentProps<typeof CarouselPrimitive.Item>, JsxStyleProps>
>(CarouselPrimitive.Item, 'item')
 
const PreviousButton = React.forwardRef<
  React.ComponentRef<typeof CarouselPrimitive.Previous>,
  PreviousProps
>((props, ref) => {
  const [buttonProps, { className, children, ...restProps }] = button.splitVariantProps(props)
  return (
    <CarouselPrimitive.Previous
      ref={ref}
      className={cx(button({ variant: 'text', ...buttonProps }), className)}
      {...restProps}
    >
      {children}
    </CarouselPrimitive.Previous>
  )
})
 
export const Previous = withContext<
  React.ComponentRef<typeof CarouselPrimitive.Previous>,
  PreviousProps
>(PreviousButton, 'previous')
 
const NextButton = React.forwardRef<
  React.ComponentRef<typeof CarouselPrimitive.Next>,
  PreviousProps
>((props, ref) => {
  const [buttonProps, { className, children, ...restProps }] = button.splitVariantProps(props)
  return (
    <CarouselPrimitive.Next
      ref={ref}
      className={cx(button({ variant: 'text', ...buttonProps }), className)}
      {...restProps}
    >
      {children}
    </CarouselPrimitive.Next>
  )
})
 
export const Next = withContext<React.ComponentRef<typeof CarouselPrimitive.Next>, NextProps>(
  NextButton,
  'next',
)
 
export const Dots = withContext<
  React.ComponentRef<typeof CarouselPrimitive.Dots>,
  Assign<ComponentProps<typeof CarouselPrimitive.Dots>, JsxStyleProps>
>(CarouselPrimitive.Dots, 'dots')
 
export const Dot = withContext<
  React.ComponentRef<typeof CarouselPrimitive.Dot>,
  Assign<CarouselPrimitive.CarouselDotProps, JsxStyleProps>
>(CarouselPrimitive.Dot, 'dot')
 
const Carousel = {
  Root,
  List,
  Item,
  Previous,
  Next,
  Dots,
  Dot,
  useCarousel: CarouselPrimitive.useCarousel,
}
 
export default Carousel

Update the import paths to match your project setup

Usage

import Carousel from '@/components/ui/carousel'
<Carousel.Root opts={{ axis: 'x' }}>
  <Carousel.List>
    <Carousel.Item>
      <div>Slide 1</div>
    </Carousel.Item>
    <Carousel.Item>
      <div>Slide 2</div>
    </Carousel.Item>
  </Carousel.List>
  
  <Carousel.Previous>
    <ChevronLeft />
  </Carousel.Previous>
  <Carousel.Next>
    <ChevronRight />
  </Carousel.Next>
  
  <Carousel.Dots>
    <Carousel.Dot index={0} />
    <Carousel.Dot index={1} />
  </Carousel.Dots>
</Carousel.Root>

Examples

Basic Carousel

Slide 1
Slide 2
Slide 3
Slide 4

Vertical Carousel

Slide 1
Slide 2
Slide 3
Slide 4

Multiple Items

Slide 1
Slide 2
Slide 3
Slide 4

API Reference

Carousel.Root

The root carousel element that wraps the entire component.

Props:

  • opts - CarouselOptions - Configuration options for the carousel
  • plugins - CarouselPlugin[] - Array of plugins to use
  • setApi - function - Callback to receive the carousel API
  • orientation - 'horizontal' | 'vertical' - Orientation of the carousel (default: 'horizontal')

Carousel.List

The container that holds all carousel items.

Carousel.Item

Individual carousel slide/item.

Carousel.Previous

Button to navigate to the previous slide.

Props:

  • asChild - boolean - Whether to render as a child element (default: false)
  • All button props are supported

Carousel.Next

Button to navigate to the next slide.

Props:

  • asChild - boolean - Whether to render as a child element (default: false)
  • All button props are supported

Carousel.Dots

Container for dot indicators.

Carousel.Dot

Individual dot indicator.

Props:

  • index - number - The index of the slide this dot represents
  • asChild - boolean - Whether to render as a child element (default: false)

useCarousel Hook

Hook to access carousel context and methods.

Returns:

  • carouselRef - Ref for the carousel container
  • api - Carousel API instance
  • scrollPrev - Function to scroll to previous slide
  • scrollNext - Function to scroll to next slide
  • canScrollPrev - boolean - Whether previous slide is available
  • canScrollNext - boolean - Whether next slide is available
  • onDotButtonClick - Function to handle dot clicks
  • selectedIndex - number - Currently selected slide index
  • scrollSnaps - number[] - Array of snap points

Built with ❤️ by the carbonteq team. The source code is available on GitHub.

© 2025 Pallas UI. All rights reserved.