Koala UI

Carousel

A horizontal slide viewer with a clickable indicator. The track translates between full-width slides, arrow keys step it, and the indicator ships with a closed set of forms: dots, lines, fraction, thumbnails.

A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky

Installation#

# One-time setup (tokens + lib helpers)npx koalaui-cli@latest init# Add this component (its dependencies come along)npx koalaui-cli@latest add carousel

Usage#

usage.tsxTSX
import {  Carousel, CarouselContent, CarouselSlide, CarouselIndicators,} from "@/components/ui/carousel"export function Example() {  return (    <Carousel label="Product highlights">      <CarouselContent>        <CarouselSlide>{/* … */}</CarouselSlide>        <CarouselSlide>{/* … */}</CarouselSlide>      </CarouselContent>      <CarouselIndicators />    </Carousel>  )}

Indicator variants#

The indicator ships as one component with a closed set of forms, picked with the variant prop. Never hand-roll a new indicator per carousel: pick the form that fits the surface.

  • dots (default): pill-morphing bullets, for most cards and testimonials.
  • lines: thin fixed-width ticks, a quieter alternative to dots.
  • fraction: a contained 2 / 5 readout for dense image galleries; the active number rolls like an odometer, and the pill grows smoothly by one digit-width when the count crosses a boundary (99 / 100).
  • thumbnails: one slide preview per slide; pass a thumbnails node array indexed to the slides. A single brand ring glides from tile to tile rather than toggling per preview.
  • tabs: one text label per slide; pass a labels array indexed to the slides. A single underline glides to the active tab rather than toggling per label.
  • numbers: a numbered chip per slide; the active one fills like a numbered pager. Good for short, countable sets.
  • progress: a single continuous bar that fills with position (25% on slide 1 of 4). A readout, not per-slide clickable; navigate with arrows, drag, or the arrow keys.
dots
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
lines
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
fraction
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
thumbnails
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
tabs
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
numbers
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
progress
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky

Contained#

Pass contained to seat dots, lines or progress in a pill, the same one fraction wears. In the flow it is a muted fill; with overlay it turns dark and frosted so the white dots hold on any photo.

dots
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
lines
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
progress
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
dots · overlay
A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky

Over a hero#

Positioning is orthogonal to the form: any variant composes with overlay (float over the image, white treatment) and align (end bottom-right or center bottom-centered). Full-bleed heroes usually want centered overlay dots.

Sunlit dining area with wood floors and floor-to-ceiling windows
Dining room
Bright living room with arched windows and a wood stove
The great room
Minimal kitchen in white and walnut
Kitchen
Dark luxe kitchen with walnut cabinetry and a green bar stool
Walnut bar

On images / cards#

For photo galleries, add CarouselPrevious / CarouselNext: overlay arrows that reveal on hover (and on keyboard focus), and stay hidden at the first/last slide. Pass overlay to CarouselIndicators to float the dots over the bottom-right of the image; over photos they switch to fixed white so they stay legible on any background.

Sunlit dining area with wood floors and floor-to-ceiling windows
Dining room
Bright living room with arched windows and a wood stove
The great room
Minimal kitchen in white and walnut
Kitchen
Dark luxe kitchen with walnut cabinetry and a green bar stool
Walnut bar

Product gallery#

thumbnailSize sets the thumbnail tile: sm (the default, 56×40) suits landscape photos, lg is a 64px square for product packshots, where a landscape crop would cut the object in half. The gliding ring resizes with the tiles. This is the gallery on the ecommerce product pages.

Everyday Backpack in navy, standing on a tiled floor
The padded top handle and main zip
Water-resistant twill with the woven label
The front pocket and side profile

Controlled#

Pass index and onIndexChange to drive the active slide from your own state, e.g. to pair the dots with external prev/next buttons or a step counter. Omit them for uncontrolled use with defaultIndex.

A-frame cabin lit at dusk beside a firepit and Adirondack chairs
Modern black cabin in an autumn forest with a glowing firepit
Two dark timber cabins with a lit deck at dusk
Black A-frame cabin against a pink dusk sky
1 / 4

FAQ#

Carousel is a slide viewer: it translates a track between full-width slides with clickable indicator dots. Pagination is the page toolbar on the data table. If you are paging through tabular records rather than swiping through panels, reach for Pagination.