Framework Guides

React and Next.js

Use Blossom Carousel in React and Next.js apps with tsx, global styles, and semantic root elements.

Install

pnpm add @blossom-carousel/react

bun add @blossom-carousel/react

yarn add @blossom-carousel/react

npm install @blossom-carousel/react

React usage

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

export function App() {
  return (
    <BlossomCarousel>
      {Array.from({ length: 12 }, (_, index) => (
        <div key={index}>Slide {index + 1}</div>
      ))}
    </BlossomCarousel>
  );
}

Next.js setup

Import the core stylesheet from a global entry point.

app/layout.tsx

import "@blossom-carousel/core/style.css";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

Then render the carousel from a component.

BlossomCarousel.tsx

import { BlossomCarousel } from "@blossom-carousel/react";

export function FeaturedCarousel() {
  return (
    <BlossomCarousel>
      {Array.from({ length: 12 }, (_, index) => (
        <div key={index}>Slide {index + 1}</div>
      ))}
    </BlossomCarousel>
  );
}

Semantic root element

<BlossomCarousel as="ul">
  {Array.from({ length: 12 }, (_, index) => (
    <li key={index}>Slide {index + 1}</li>
  ))}
</BlossomCarousel>;

Button controls

Navigate the carousel programmatically with prev() and next().

import { useRef } from "react";

export function App() {
  const blossomCarousel = useRef(null);

  return (
    <>
      <BlossomCarousel ref={blossomCarousel}>
        {Array.from({ length: 12 }, (_, index) => (
          <div key={index}>Slide {index + 1}</div>
        ))}
      </BlossomCarousel>

      <button onClick={() => blossomCarousel.current.prev()}>Previous</button>
      <button onClick={() => blossomCarousel.current.next()}>Next</button>
    </>
  );
}

Overscroll API

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

import { useRef } from "react";
import { BlossomCarousel } from "@blossom-carousel/react";

export function App() {
  const blossomCarousel = useRef<HTMLElement | null>(null);

  function onOverscroll(event: CustomEvent<{ left: number }>) {
    // prevent and overwrite Blossom's default rubberbanding effect
    event.preventDefault();

    const overScroll = event.detail.left;

    Array.from(blossomCarousel.current?.children ?? []).forEach((slide) => {
      (slide as HTMLElement).style.transform = `scale(${1 - overScroll * 0.1})`;
    });
  }

  return (
    <BlossomCarousel
      ref={blossomCarousel}
      onOverscroll={(event) => {
        onOverscroll(event as CustomEvent<{ left: number }>);
      }}
    >
      {Array.from({ length: 12 }, (_, index) => (
        <div key={index}>Slide {index + 1}</div>
      ))}
    </BlossomCarousel>
  );
}

Vue and Nuxt

Use Blossom Carousel in Vue and Nuxt apps with local imports or global plugin registration.

Svelte and SvelteKit

Use Blossom Carousel in Svelte and SvelteKit with keyed each blocks and global stylesheet imports.