Fade

The Fade plugin allows you to replace the default sliding transition of Embla Carousel with a smooth cross-fade effect. When this plugin is active, slides are layered on top of each other, and their opacity is manipulated based on the carousel's scroll progress.

Installation

First, install the embla-carousel-fade package via your package manager:

npm install embla-carousel-fade

Usage

To enable the fade effect, import the Fade plugin and pass it to the Embla Carousel constructor or hook in the plugin array.

Vanilla JS

import EmblaCarousel from 'embla-carousel'
import Fade from 'embla-carousel-fade'

const viewportNode = document.querySelector('.embla__viewport')
const options = { loop: true }
const plugins = [Fade()]

const emblaApi = EmblaCarousel(viewportNode, options, plugins)

React

import React from 'react'
import useEmblaCarousel from 'embla-carousel-react'
import Fade from 'embla-carousel-fade'

export function EmblaCarousel() {
  const [emblaRef] = useEmblaCarousel({ loop: true }, [Fade()])

  return (
    <div className="embla" ref={emblaRef}>
      <div className="embla__container">
        <div className="embla__slide">Slide 1</div>
        <div className="embla__slide">Slide 2</div>
        <div className="embla__slide">Slide 3</div>
      </div>
    </div>
  )
}

Required CSS

For the cross-fade effect to work correctly, slides must be positioned to overlap within the container. The plugin handles the opacity transitions, but you must ensure the slides occupy the same space via CSS:

.embla__container {
  display: flex;
  /* Allow slides to stack if necessary, though 
     the plugin often manages the layout */
}

.embla__slide {
  flex: 0 0 100%;
  min-width: 0;
  /* Ensure only the active slide is interactable if needed */
}

Options

The Fade plugin accepts an optional options object to customize its behavior.

Example with Options

const plugins = [
  Fade({
    active: true
  })
]

API Methods

Once the plugin is initialized, you can access its methods through the plugins() method of the Embla API.

const fadePlugin = emblaApi.plugins().fade

if (fadePlugin) {
  // Access plugin-specific logic if available
}

TypeScript

The Fade plugin is fully typed. You can import the FadeOptionsType if you need to define your configuration outside of the initialization:

import { FadeOptionsType } from 'embla-carousel-fade'

const customOptions: FadeOptionsType = {
  active: true
}