react-responsive-3d-carousel v2.1.5

A 3D carousel component for React, designed to create immersive, interactive experiences for your users.

🌟 Features

• 3D rotation effect for an eye-catching carousel experience
• Customizable speed, direction, and number of visible items
• Responsive design, adaptable to various screen sizes
• Easy to use with simple props and hooks

🔗 Important Links

• Documentation
• Layout Editor
• Storybook
• Github Repository

🚀 Getting Started

Installation

Install the library via npm:

npm install react-responsive-3d-carousel

Or with Yarn:

yarn add react-responsive-3d-carousel

Basic Usage

Here's a simple example of how to use the 3D Carousel in your React project:

import React from 'react'
import { Carousel } from 'react-responsive-3d-carousel'
import 'react-responsive-3d-carousel/dist/styles.css'

const items = [
  <img src="image1.jpg" alt="image1" />,
  <video src="video1.mp4" autoPlay />,
  <div>Custom Content 1</div>,
]

function App() {
  return (
    <div className="App">
      <Carousel
        items={items}
        startIndex={0}
        onChange={(currentIndex) => console.log(currentIndex)}
      />
    </div>
  )
}

export default App

Note: Make sure to import the CSS file to properly style the Carousel. Otherwise import react-responsive-3d-carousel/dist/index.esm.min.js which includes the CSS.

📚 Documentation

Check out the full documentation.

Carousel Props

Default Option Props

These props are only effective when layout is set to 'default'.

Custom Layout (CarouselLayoutInfo)

Try using the Custom Layout Editor !

CarouselLayoutInfo lets you define custom layouts for carousel items, controlling each item’s size, position, and rotation relative to the selected item. Each CarouselLayoutInfo entry consists of multiple LayoutInfo objects applied to items based on their index.

The default layout uses the same structure. See Example.

LayoutInfo

By default, each carousel item is centered within the container.

export type LayoutInfo = {
  width?: number | string // scales with container width if a number. When it's undefined or 'auto', the width prop is used.
  height?: number | string // scales with container height if a number. When it's undefined or 'auto', the height prop is used.
  translate: {
    x: number | string // scales with container width if a number
    y: number | string // scales with container height if a number
    z: number | string // scales with container width if a number
  }
  rotate: {
    x: number // in degrees
    y: number // in degrees
    z: number // in degrees
  }
  offset: {
    x: number | string // scales with item width if a number
    y: number | string // scales with item height if a number
    z: number | string // scales with item width if a number
  }
}

CarouselLayoutInfo

CarouselLayoutInfo defines the layout for each carousel item, including a default-key layout used when no specific layout is provided.

• 0: Represents the selected item
• Positive numbers: For upcoming items
• Negative numbers: For previous items

export type CarouselLayoutInfo = {
  default: LayoutInfo
  [key: number]: LayoutInfo
}

Arrows Props

Arrows props are sub-fields used under the arrows object prop in the Carousel component.

Indicators Props

Indicators props are sub-fields used under the indicators object prop in the Carousel component.

Status Props

Status props are sub-fields used under the status object prop in the Carousel component.

🗂️ Context API

The CarouselContext is a React context that provides access to the current index of the carousel. This makes it easy to integrate custom behaviors based on the carousel's current state.

type DefaultContext = {
  curIndex: number
  setCurIndex: React.Dispatch<React.SetStateAction<number>>
  slideNext: () => void
  slidePrev: () => void
}

Use the CarouselContext within the <Carousel /> component. For example, you can access it in any React component passed as the items or children prop.

import React, { useContext } from 'react'
import { CarouselContext } from 'react-responsive-3d-carousel'

function CarouselItem() {
  const { curIndex, setCurIndex } = useContext(CarouselContext)

  return (
    <div>
      <p>Current Slide: {curIndex}</p>
      <button onClick={() => setCurIndex(0)}>Go to first slide</button>
    </div>
  )
}

🎨 Customization

• You can fully customize the carousel by overriding its default CSS styles.
• To prevent style conflicts, all class names are prefixed with react-responsive-3d-carousel. Refer to the images below for details on each class name.

Carousel

Arrows

• The *-container class positions the component with position: absolute and applies pointer-events: none to prevent interference with user interactions over carousel items.
• Access each arrow button using the button child selector.

Status and Indicators

• The *-container classes position the components with position: absolute and applies pointer-events: none to prevent interference with user interactions over carousel items.
• Use the p child selector to style the status text.
• Use the ul and li child selectors to style indicators.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the CONTRIBUTING.md if you want to contribute.

⭐️ Show Your Support

If you like this project, please give it a ⭐️ on GitHub!