Embla Carousel React Component

A lightweight carousel library for React, based on Embla Carousel.

• Features
• Installation
• Basic Usage
• Component API
• Examples
• Acknowledgement
• License

Features

This library helps build carousels with declarative API. Easy to use, yet still powerful when needed.

• Comparison with Embla Carousel React:

  You need to rely on external CSS to lay out the slide container. It's not optimal in case you want to reuse the carousel somewhere with different slide sizes.

  This library comes with minimal styles needed to layout the grid, giving developers the ability to define the slide sizes in the component itself, while leaving the rest completely unstyled.

• Comparison with @mantine/carousel:

  @mantine/carousel introduces its own way to define carousel options. In contrast, this library gives you a familiar experience just like working with the base Embla Carousel React.

  The former comes with limited customization on controller components (Prev/Next Buttons or Indicator Dots) as they're tied to the Carousel. This library allows you to fully customize how those components look.

  This library also comes with a thumbs component if you need to build a product gallery for an e-commerce use case.

Installation

npm install embla-carousel-react-component

Basic Usage

import Carousel from 'embla-carousel-react-component';

<Carousel>
  {[...Array(5).keys()].map((n) => (
    <Carousel.Slide key={n}>
      <div>Slide {n + 1}</div>
    </Carousel.Slide>
  ))}
</Carousel>;

View all the examples

Component API

Carousel

| Prop | Type | Default | Description | | ------------------ | ------------------------------------ | -------------------------- | --------------------------------------------------------------------------------------------- | | perView | number \| "custom" | 1 | The number of slides per view. Pass "custom" if you want to customize the slide sizes later. | | containerStyle | React.CSSProperties | | Customize the container's style | | gap | string \| number | 16 | The spacing between slides. String is interpreted as is. Number is interpreted as pixel unit. | | options | EmblaOptionsType | See here | Embla Carousel's options | | plugins | EmblaPluginType[] | | Embla Carousel's plugins | | PrevButton | () => JSX.Element | | Previous Button component | | NextButton | () => JSX.Element | | Next Button component | | Indicators | () => JSX.Element | | Dot Indicators component | | Thumbs | () => JSX.Element | | Thumbs component | | thumbsOptions | EmblaOptionsType | See here | Options for Thumbs component | | thumbsPlugins | EmblaPluginType[] | | Plugins for Thumbs component | | getEmblaApi | (embla: EmblaCarouselType) => void | | Access Embla API for advanced use cases |

options

The component comes with a few opinionated options to ensure it works properly out of the box.

{
  align: 'start',
  slidesToScroll: 'auto',
  containScroll: 'trimSnaps'
}

You can overwrite this by providing your own styles.

Carousel.Slide

| Prop | Type | Default | Description | | -------- | -------- | ------- | ---------------------------------------------------------------------------------------------- | | size | string | | The slide size. To you this option, you need to pass perView="custom" on Carousel component. |

Carousel.PrevButton, Carousel.NextButton

| Prop | Type | Default | Description | | --------------------- | -------- | ------------ | ---------------------------- | | disabledClassName | string | "disabled" | ClassName for disabled state |

The components also expose a data-disabled attribute that you can use to conditionally apply different styles.

Carousel.Indicators

| Prop | Type | Default | Description | | ------------------------ | -------- | ------------ | ------------------------------------------------------------------- | | selectedClassName | string | "selected" | ClassName for selected state | | nonSelectedClassName | string | | ClassName for non-selected state (Tailwind CSS users may need this) |

The component also exposes a data-selected attribute that you can use to conditionally apply different styles.

Carousel.Thumbs

| Prop | Type | Default | Description | | ----------- | ------------------ | ------- | --------------------------------------------------------------------------------------------- | | perView | number | 1 | The number of thumbs per view | | gap | string \| number | 8 | The spacing between thumbs. String is interpreted as is. Number is interpreted as pixel unit. |

thumbsOptions

Default options:

{
  containScroll: 'keepSnaps',
  dragFree: true,
}

Carousel.Thumb

| Prop | Type | Default | Description | | ------------------------ | -------- | ------------ | ------------------------------------------------------------------- | | index | number | required | The index of thumb item | | selectedClassName | string | "selected" | ClassName for selected state | | nonSelectedClassName | string | | ClassName for non-selected state (Tailwind CSS users may need this) |

The component also exposes a data-selected attribute that you can use to conditionally apply different styles.

Examples

Basic

• Default
• Loop
• Right To Left
• Slides To Scroll
• Drag Free
• Align
• VariableWidths
• YAxis

Plugins

• Autoplay
• Class Names
• Wheel Gestures

Others

• Responsive
• Arrows and Dots
• Thumbnails
• Scroll Progress
• Parallax

Acknowledgement

• This library cannot be possible without Embla Carousel React. It really is a lightweight and sleek library for building carousels.
• This library also takes @mantine/carousel as a reference, especially the idea of exposing emblaApi to the outside.

License

MIT