embla-page-scroll-plugin

A seamless plugin for Embla Carousel that syncs your carousel with page scrolling, creating an interactive and engaging user experience.

Features

• Automatically moves your carousel as users scroll through the page
• Customizable scrolling speed
• Smooth user experience with native-feeling interactions
• Works with mouse scrolling and touch scrolling
• Compatible with all Embla Carousel options and other plugins

Installation

npm install embla-page-scroll-plugin
# or
yarn add embla-page-scroll-plugin
# or
pnpm add embla-page-scroll-plugin

Usage

Basic Usage

import React from "react";
import useEmblaCarousel from "embla-carousel-react";
import { usePageScrollEmbla } from "embla-page-scroll-plugin";

const YourCarousel = () => {
  // Create the plugin with default options
  const pageScrollPlugin = usePageScrollEmbla();

  // Initialize Embla with the plugin
  const [emblaRef] = useEmblaCarousel(
    {
      // Your Embla options here
      loop: true,
      align: "center",
    },
    [pageScrollPlugin]
  );

  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>
  );
};

export default YourCarousel;

With Custom Speed

import React from "react";
import useEmblaCarousel from "embla-carousel-react";
import { usePageScrollEmbla } from "embla-page-scroll-plugin";

const YourCarousel = () => {
  // Create the plugin with custom speed
  const pageScrollPlugin = usePageScrollEmbla({
    speed: 15, // Higher number = faster response to scrolling
  });

  // Initialize Embla with the plugin
  const [emblaRef] = useEmblaCarousel({}, [pageScrollPlugin]);

  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>
  );
};

export default YourCarousel;

Options

The usePageScrollEmbla function accepts the following options:

| Option | Type | Default | Description | | ------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------- | | speed | number | 10 | Controls how responsive the carousel is to scrolling. Higher values make the carousel move faster in response to page scrolling |

Examples

Full Example with Next.js

"use client";

import { useState, useEffect, useCallback } from "react";
import useEmblaCarousel from "embla-carousel-react";
import ClassNames from "embla-carousel-class-names";
import Image from "next/image";
import { usePageScrollEmbla } from "embla-page-scroll-plugin";

const images = ["/image1.jpg", "/image2.jpg", "/image3.jpg", "/image4.jpg"];

export default function ImageCarousel() {
  // Initialize plugin with speed option
  const pageScrollPlugin = usePageScrollEmbla({
    speed: 15,
  });

  const [emblaRef, emblaApi] = useEmblaCarousel(
    {
      loop: true,
      align: "center",
      containScroll: "trimSnaps",
      dragFree: false,
      breakpoints: {
        "(min-width: 1024px)": { align: "end" },
      },
    },
    [ClassNames(), pageScrollPlugin]
  );

  const [selectedIndex, setSelectedIndex] = useState(0);

  const onSelect = useCallback(() => {
    if (!emblaApi) return;
    setSelectedIndex(emblaApi.selectedScrollSnap());
  }, [emblaApi]);

  useEffect(() => {
    if (!emblaApi) return;
    emblaApi.on("select", onSelect);
    onSelect();

    return () => {
      emblaApi.off("select", onSelect);
    };
  }, [emblaApi, onSelect]);

  return (
    <div className="relative overflow-hidden" ref={emblaRef}>
      <div className="flex">
        {images.map((src, index) => (
          <div className="flex-shrink-0 mr-4" key={index}>
            <Image
              src={src}
              alt={`Slide ${index}`}
              className="object-cover w-full h-full rounded-md"
              height={435}
              width={600}
            />
          </div>
        ))}
      </div>
    </div>
  );
}

How It Works

The embla-page-scroll-plugin creates a seamless connection between page scrolling and your carousel movement. As users scroll down the page, the carousel smoothly progresses through its slides, creating an engaging and interactive viewing experience.

The plugin works by:

1. Monitoring the page's scroll position
2. Translating vertical scroll movements into horizontal carousel movements
3. Creating synthetic pointer events to move the carousel in a natural way
4. Handling both touch and mouse interactions

This creates a natural, intuitive experience where content reveals itself as the user scrolls, perfect for showcasing portfolios, product features, or storytelling websites.

Browser Support

This plugin works in all modern browsers that support Embla Carousel.

GitHub Repository

https://github.com/widejoy/embla-page-scroll-plugin

License

MIT