A customizable React carousel component
npm install movii-carouselνκ΅μ΄ | English
A customizable, lightweight React carousel component with support for single and multiple slides, auto-play, infinite loop, and more.
- π Single & Multi-slide views - Display one or multiple slides at once
- βΎοΈ Infinite loop - Seamless infinite scrolling
- β±οΈ Auto-play mode - Automatic slide transitions with customizable intervals
- π± Responsive - Adapts to container size
- π¨ Fully customizable - Custom buttons, pagination, and progress bar
- π― TypeScript support - Full type safety
- π¦ Zero dependencies - Lightweight and fast
- βΏ Accessible - ARIA labels and keyboard navigation support
- π¨ Tailwind CSS optimized - You can override styles with tailwindcss's utility classes.
``bash`
npm install movii-carouselor
yarn add movii-carouselor
pnpm add movii-carousel
For the best development experience with Tailwind CSS IntelliSense, add this to your .vscode/settings.json:
`json`
{
"tailwindCSS.classAttributes": [".[cC]lass."]
}
This enables Tailwind CSS autocomplete for all class-related props (e.g., className, containerClassName, dotClassName, etc.).
`tsx
import { Carousel } from 'movii-carousel';
import 'movii-carousel/carousel.css';
function App() {
return (
Slide 1
Slide 2
Slide 3
);
}
`
The root component that wraps the entire carousel.
#### Props
| Prop | Type | Default | Description |
| --------------- | ------------------------------------- | ---------- | -------------------------------------------------------------- |
| mode | 'auto' \| 'manual' | 'manual' | Slide transition mode |loop
| | boolean | false | Enable infinite loop (automatically true in auto mode) |autoInterval
| | number | 5000 | Auto slide interval in milliseconds (only in auto mode) |initialIndex
| | number | 0 | Initial slide index |slidesPerView
| | number | 1 | Number of slides visible per view |spaceBetween
| | number | 0 | Space between slides in pixels (only when slidesPerView > 1) |onSlideChange
| | (index: number \| number[]) => void | - | Callback when slide changes |
Container for carousel slides. Each child element becomes a slide.
#### Props
Extends HTMLDivElement props (className, style, etc.)
Button to navigate to the previous slide.
#### Props
Extends HTMLButtonElement props. Automatically disabled at the first slide when loop={false}.
Button to navigate to the next slide.
#### Props
Extends HTMLButtonElement props. Automatically disabled at the last slide when loop={false}.
Displays pagination dots for navigation.
> Note: Cannot be used when slidesPerView > 1
#### Props
| Prop | Type | Description |
| -------------------- | ------------------------------------------------- | ------------------------------ |
| containerClassName | string | Custom class for container |dotClassName
| | string | Custom class for inactive dots |activeDotClassName
| | string | Custom class for active dot |renderDot
| | (index: number, isActive: boolean) => ReactNode | Custom dot renderer |
Displays a progress bar indicating current position.
> Note: Cannot be used when slidesPerView > 1
#### Props
| Prop | Type | Description |
| --------------- | -------- | ------------------------------ |
| className | string | Custom class for container |fillClassName
| | string | Custom class for progress fill |
`tsx`
Slide 1
Slide 2
Slide 3
`tsx`
Slide 1
Slide 2
Slide 3
`tsx`
Slide 1
Slide 2
Slide 3
Slide 4
Slide 5
`tsx`
Slide 1
Slide 2
Slide 3
β
β
`tsx`
Slide 1
Slide 2
Slide 3
{index + 1}
)}
/>
The carousel comes with minimal default styles. You can customize it using:
1. CSS classes - Override default classes
2. Inline styles - Pass style or className propsrenderDot
3. Custom components - Use for pagination
- .carousel-root - Root container.carousel-content
- - Content wrapper.carousel-content-multi
- - Content wrapper (multi-slide).carousel-button
- - Navigation buttons.carousel-button-prev
- - Previous button.carousel-button-next
- - Next button.carousel-button-icon
- - Button icon SVG.carousel-pagination
- - Pagination container.carousel-pagination-dot
- - Pagination dot.carousel-pagination-dot-active
- - Active pagination dot.carousel-progress-bar
- - Progress bar container.carousel-progress-bar-fill
- - Progress bar fill
Access carousel state from child components.
`tsx
import { useCarouselState } from 'movii-carousel';
function CustomComponent() {
const {
currentSlideIndex,
activeSlideIndex,
totalItemLength,
mode,
loop,
autoInterval,
isTransitioning,
slidesPerView,
spaceBetween,
} = useCarouselState();
return
$3
Access carousel actions from child components.
`tsx
import { useCarouselActions } from 'movii-carousel';function CustomControls() {
const { goToSlide, goToPrev, goToNext } = useCarouselActions();
return (
);
}
`TypeScript
This package is written in TypeScript and includes type definitions.
`tsx
import type { CarouselRootProps } from 'movii-carousel';const props: CarouselRootProps = {
mode: 'auto',
loop: true,
autoInterval: 3000,
};
``- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
MIT Β© Moon-Sangho
Contributions are welcome! Please feel free to submit a Pull Request.