Carousel Component
React carousel with arrows, dots, looping, autoplay with hover pause, touch swipe, keyboard navigation and reduced-motion support.
Import
1import { Carousel } from "@neuctra/ui";Basic Usage
Each child becomes a slide. Arrow keys, swipe and the dots all navigate.
Autoplay
autoPlay advances on an interval and pauses on hover or focus.
Minimal (no arrows, no loop)
Props
All available props for the Carousel component.
| Prop | Type | Default | Description |
|---|---|---|---|
| children | ReactNode | — | Slides (required) |
| defaultIndex | number | 0 | Initial slide |
| onIndexChange | (index: number) => void | — | Fired on every slide change |
| autoPlay | number | 0 | Interval in ms; 0 disables. Pauses on hover/focus |
| loop | boolean | true | Wrap around at the ends |
| showArrows | boolean | true | Prev/next buttons |
| showDots | boolean | true | Dot indicators |
| label | string | "Carousel" | Accessible region name |
| trackClassName | string | — | Styles the overflow-hidden track wrapper. |
| slidesClassName | string | — | Styles the sliding flex container that holds all slides. |
| slideClassName | string | — | Styles each individual slide wrapper. |
| arrowClassName | string | — | Styles both the previous and next arrow buttons. |
| prevArrowClassName | string | — | Styles the previous arrow button. |
| nextArrowClassName | string | — | Styles the next arrow button. |
| arrowIconClassName | string | — | Styles the chevron icons inside the arrow buttons. |
| dotsClassName | string | — | Styles the dots container. |
| dotClassName | string | — | Styles each individual dot button. |
Accessibility
- Renders role="region" with aria-roledescription="carousel"; each slide is a labelled group ("Slide 2 of 5").
- Hidden slides are inert and aria-hidden, so their links are unreachable until active.
- Arrow keys navigate while focused; the slide transition is disabled under prefers-reduced-motion.
- Autoplay pauses on hover and keyboard focus (WCAG 2.2.2).
Frequently Asked Questions
How do I install and import the Carousel component?
Install the @neuctra/ui package, then import it with: import { Carousel } from "@neuctra/ui";
Can I customize the Carousel component's appearance?
Yes. Carousel accepts a className prop for custom Tailwind CSS classes, so you can adjust spacing, layout, and styling without overriding the component internals.
Is the Carousel component accessible?
Carousel is built with semantic HTML and standard ARIA attributes, and supports keyboard navigation and focus states out of the box, so it works well with screen readers and keyboard-only users.