@carousel-ui/react-spin-carousel-3d v1.0.18
React Spin Carousel 3D 🎠
The React Spin Carousel 3D is a highly customizable 3D carousel component for React. It allows you to display a collection of items in a visually appealing 3D carousel with smooth transitions and interactive controls. The component supports auto-play, custom radio buttons, smooth animations and multiple display modes("card", "image"). Perfect for showcasing portfolios, products, or image galleries and many more :).
📦 Installation
npm install @carousel-ui/react-spin-carousel-3d
# or
yarn add @carousel-ui/react-spin-carousel-3d🌟 Features
- 3D Perspective Effects - Realistic card rotation and depth
- Dual Display Modes -
card(with shadows/borders) andimage(seamless) modes - Responsive Design - Works on all screen sizes
- Touch & Drag Support - Mobile-friendly interactions
- Auto-play - Optional automatic rotation
- Customizable Navigation - Built-in radio buttons or bring your own
- TypeScript Support - Fully typed components
- Performance Optimized - Smooth animations with CSS transforms
Usage
Complete usage Examples
🛠 Props Reference
Core Props
| Prop | Type | Default | Description |
|---|---|---|---|
data | T[] | Required | Array of items to render |
renderItem | (item: T, index: number) => React.ReactNode | Required | Render function for each item |
Layout & Styling
| Prop | Type | Default | Description |
|---|---|---|---|
width | string \| number | "100vw" | Container width (px or %) |
height | string \| number | 300 | Container height (px or %) |
itemWidth | string \| number | 300 | Individual item width (px or %) |
accentColor | string | "hsl(204, 5%, 38%)" | Color for active states |
backgroundColor | string | "#F5F5F5" | Background color for card mode |
containerStyle | React.CSSProperties | {} | Custom styles for container div |
itemStyle | React.CSSProperties | {} | Custom styles for individual items |
Behavior & Functionality
| Prop | Type | Default | Description |
|---|---|---|---|
initialActiveIndex | number | Middle index | Starting active item index |
isAutoPlay | boolean | false | Enable automatic rotation |
autoPlayInterval | number | 5000 | Rotation interval in milliseconds |
onItemClick | (item: T, index: number) => void | - | Callback when item is clicked |
Display Mode
| Prop | Type | Default | Description |
|---|---|---|---|
displayMode | "image" \| "card" | "card" | Visual presentation style |
imageFit | "cover" \| "contain" \| "fill" | "cover" | Image scaling behavior (image mode) |
imagePosition | string | "center" | Image positioning (e.g. "top left") |
Navigation Controls
| Prop | Type | Default | Description |
|---|---|---|---|
showRadioButtons | boolean | true | Show default navigation indicators |
customRadioButtons | (index, isActive, setActiveIndex) => React.ReactNode | - | Custom navigation component |
radioButtonStyle | React.CSSProperties | {} | Styles for default navigation dots |
Advanced Configuration
| Prop | Type | Default | Description |
|---|---|---|---|
key | string | - | Unique identifier for carousel |
🎨 Styling Tips
For Cards:
- Use
backgroundColorto set card color - Add custom shadows via
itemStyle
itemStyle={{ boxShadow: "0 10px 20px rgba(0,0,0,0.2)", borderRadius: "12px" }}- Use
For Images:
- Set
imageFit="contain"for full image visibility - Use
imagePosition="top"for portrait images
- Set
⚠️ Troubleshooting
Issue: Auto-play stops on hover
Solution: This is intentional (UX best practice). Lets the user observe whats inside the card while hovering!
Issue: Radio buttons not properly working when using multiple carousels in same page
Solution: Use unique key on each carousel
Issue: Horizontal scroll appears
Fix: Ensure parent container has overflow-x: hidden
Issue: Items overlapping
Fix: Increase itemWidth or reduce number of items
🤝 Contributing
Contributions, issues and feature requests are welcome!
Feel free to check the issues page.
If you'd like to improve this project, please:
- Fork the repository
- Create your feature branch:
git checkout -b feature/your-feature-name - Commit your changes:
git commit -m 'Add some feature' - Push to the branch:
git push origin feature/your-feature-name - Open a pull request
We appreciate all kinds of contributions — bug reports, feature ideas, code, and documentation!
Please add tests before submitting a PR!
📜 License
MIT © @carousel-ui