Carousel
carouselNavigates scroll-snap slides with arrows, dots, autoplay, looping, dragging, and keyboard controls.
Usage
Basic usage
Each top-level child is a slide; it has arrows + dots by default, can be dragged and dropped, and supports ←→ keyboard.
<Carousel className="w-96" aria-label="Homepage Promotion Banner">
<Slide title="618 Mid-Year Sale" />
<Slide title="Summer Thin and Light Series" />
{/* ...more promotional spots */}
</Carousel>Auto play + loop
autoplay automatically turns pages every 4s, loop lets the last page go back to the first one; automatically pauses when hovering/focusing.
<Carousel autoplay loop className="w-96">
<Slide title="618 Mid-Year Sale" />
<Slide title="Summer Thin and Light Series" />
</Carousel>Dots only
showArrows={false} Hide the left and right arrows, leaving only the bottom dot indication.
<Carousel showArrows={false} className="w-96">
<Slide title="618 Mid-Year Sale" />
<Slide title="Summer Thin and Light Series" />
</Carousel>Arrow only
showDots={false} Hide the dots and only keep the left and right switching arrows.
<Carousel showDots={false} className="w-96">
<Slide title="618 Mid-Year Sale" />
<Slide title="Summer Thin and Light Series" />
</Carousel>When to use
Use Carousel for equal-width slides shown one at a time, such as a marketing banner, gallery, or feature tour. Use Card or List grid mode for a static multi-card layout.
Import
import { Carousel } from "@hulianui/ui"Props
CarouselProps inherits native div properties except onSelect and children:
| Name | Type | Default | Description |
|---|---|---|---|
| current | number | — | Controlled slide index. |
| defaultCurrent | number | 0 | Initial uncontrolled index. |
| autoplay | boolean | false | Autoplay, forced off under reduced motion. |
| autoplayInterval | number | 4000 | Autoplay interval in milliseconds. |
| loop | boolean | false | Returns from the last slide to the first. |
| showArrows | boolean | true | Shows previous and next controls. |
| showDots | boolean | true | Shows dot indicators. |
| aria-label | string | "\u8f6e\u64ad" | Region label; the built-in Chinese means “Carousel.” |
| slideClassName | string | — | Class applied to every slide, useful for fixed height and radius. |
Events
| Event | Type | Description |
|---|---|---|
| onSelect | (index: number) => void | Called by arrows, dots, keyboard, autoplay, or drag settling. |
Slots
| Slot | Type | Description |
|---|---|---|
| children* | ReactNode | One top-level child per slide. |
Usage notes
currentmakes the component controlled and requiresonSelect; otherwise usedefaultCurrent.- Reduced motion disables autoplay, including in accessibility and test environments.
- Set consistent slide height through
slideClassNameto prevent layout jumps. - Runtime control labels are dynamic
"\u7b2c N / M \u5f20"(“Slide N of M”),"\u4e0a\u4e00\u5f20"/"\u4e0b\u4e00\u5f20"(“Previous” / “Next”),"\u5e7b\u706f\u7247\u5bfc\u822a"(“Slide navigation”), and"\u8f6c\u5230\u7b2c N \u5f20"(“Go to slide N”).
Related
Table · Book3D · ProTable · PricingTable · JsonViewer · EditableTable
Playground
<Carousel>
<Slide title="618 Mid-Year Sale" />
<Slide title="Summer Thin and Light Series" />
{/* ...more promotional spots */}
</Carousel>