Basic Carousel React component
A plain, dependable carousel: drag or swipe between slides, arrows and dots, one to four slides in view, looping, and optional autoplay whose progress fills the active dot and pauses whenever someone hovers, focuses or drags.
When to use the Basic Carousel component
Use Basic Carousel when a handful of items should share one spot on the page: hero images, featured products, testimonials or photo sets. It's deliberately plain, so it fits anywhere without drawing attention away from the content.
Keep autoplay for decorative images; for content people need to read or compare, leave it off and let them drag or use the arrows.
Installation
Add the Basic Carousel component to your project with the shadcn CLI. It lands in components/basic-carousel.tsx as plain React + Tailwind CSS source you own and can edit.
npx shadcn@latest add https://reactframe.com/r/basic-carousel.jsonOr copy the source by hand and install its dependencies:
npm install motion clsx tailwind-mergeProps
<BasicCarousel /> accepts 16 props, all optional.
| Prop | Type | Default |
|---|---|---|
| slides Image slides. Pass children instead for your own slide content. | { src: string; alt: string; title?: string; description?: string }[] | DEFAULT_SLIDES |
| children | React.ReactNode | — |
| slidesPerView How many slides show at once (1–4). | number | 1 |
| gap Space between slides, in px. | number | 12 |
| loop After the last slide, go back to the first (and the other way). | boolean | true |
| autoplay Move on by itself; pauses while hovered, focused, dragged or off-screen. | boolean | false |
| interval Milliseconds per slide when autoplaying. | number | 4000 |
| showArrows | boolean | true |
| showDots | boolean | true |
| aspectRatio Slide shape, e.g. "16 / 10" or "1 / 1". | string | "16 / 10" |
| index | number | — |
| defaultIndex | number | 0 |
- slides
Image slides. Pass children instead for your own slide content.
{ src: string; alt: string; title?: string; description?: string }[]Default: DEFAULT_SLIDES - childrenReact.ReactNode
- slidesPerView
How many slides show at once (1–4).
numberDefault: 1 - gap
Space between slides, in px.
numberDefault: 12 - loop
After the last slide, go back to the first (and the other way).
booleanDefault: true - autoplay
Move on by itself; pauses while hovered, focused, dragged or off-screen.
booleanDefault: false - interval
Milliseconds per slide when autoplaying.
numberDefault: 4000 - showArrowsbooleanDefault: true
- showDotsbooleanDefault: true
- aspectRatio
Slide shape, e.g. "16 / 10" or "1 / 1".
stringDefault: "16 / 10" - indexnumber
- defaultIndexnumberDefault: 0
Show all 16 propsShow fewer
| onIndexChange | (index: number) => void | — |
| label Accessible name for the carousel. | string | "Carousel" |
| theme | "dark" | "light" | "dark" |
| className | string | — |
- onIndexChange(index: number) => void
- label
Accessible name for the carousel.
stringDefault: "Carousel" - theme"dark" | "light"Default: "dark"
- classNamestring
FAQ
- Can it show several slides at once?
- Yes. slidesPerView shows one to four; arrows, dots and dragging then move one slide at a time and stop at the last full view unless loop is on.
- When does autoplay stop?
- It pauses while the carousel is hovered, focused or being dragged, and while the browser tab is hidden. The active dot fills up to show time until the next slide.
- Can I put my own content in the slides?
- Pass children instead of slides; each child becomes a slide with the same sizing, dragging and controls.
