Blossom Carousel Logo
GitHub
Framework Guides

Core

Use Blossom Carousel Core directly with DOM elements, lazy loading, and lifecycle cleanup.

Install

pnpm add @blossom-carousel/core

Basic setup

import { Blossom } from "@blossom-carousel/core";
import "@blossom-carousel/core/style.css";

const element = document.querySelector("#my-carousel-element");

if (element) {
  const blossom = Blossom(element);
  blossom.init();
}

Lazy loading

Lazy load Blossom Carousel only on non-touch devices.

const hasMouse = window.matchMedia(
  "(hover: hover) and (pointer: fine)",
).matches;

if (hasMouse) {
  const { Blossom } = await import("@blossom-carousel/core");
  const element = document.querySelector("#my-carousel-element");
  const blossom = Blossom(element);
  blossom.init();
}

Options

Blossom(element, options?) accepts an optional second argument.

OptionTypeDefaultDescription
repeatbooleanfalseExperimental looping mode. See the Repeat example.
const blossom = Blossom(element, { repeat: true });
Before @blossom-carousel/core 1.1.10, TypeScript required the second argument, so you had to pass {}.

Methods

After init(), the instance can smooth-scroll to the previous or next snap point, or to the adjacent slide when nothing snaps:

blossom.prev();
blossom.next({ align: "center" });

align accepts "start" (default), "center", or "end". When scroll snap is active, the slides' CSS scroll-snap-align is used instead and align is ignored.

These methods belong to the drag engine, so they aren't available when you skip loading it on touch devices. For controls that work everywhere, use the Web Components or a framework package.

Destroy

blossom.destroy();

Call destroy() during route changes, component unmounting, or whenever the carousel root will be removed from the DOM.

Overscroll API

Tap into Blossom's drag engine's overscroll behavior to create your own style.

element.addEventListener("overscroll", (event) => {
  // prevent Blossom's default rubberbanding effect
  event.preventDefault();

  const overScroll = event.detail.left;

  Array.from(event.currentTarget.children).forEach((slide) => {
    slide.style.transform = `scale(${1 - overScroll * 0.1})`;
  });
});