# Introduction

Blossom Carousel is the first carousel library that builds on native browser scrolling instead of replacing it. It provides a small drag enhancement for pointer devices while maintaining the core interaction model, performance, and accessibility of a real scroll container.

## Why Blossom Carousel?

Carousels have become a powerful and popular choice among the many ways to structure content hierarchy. They are one of the main means to create a spatial form of progressive disclosure by collapsing vertical real estate while inviting horizontal exploration. Their scrolling behavior makes them stand out especially on touch devices where swiping is such a natural gesture.

Web standards have evolved to a point where these swipable carousels feel incredibly native. However, horizontal scrolling on desktop lacks the intuitive drag interaction that makes touch-based carousels feel so natural. Blossom Carousel fills that gap with a custom, lightweight physics-based drag engine that works seamlessly on top of native scrolling.

::note{color="neutral" icon="i-lucide-lightbulb"}
Blossom's dragging engine syncs with your CSS configuration automatically.
::

::card-group
  :::card{color="neutral" icon="i-lucide-gauge" title="Native scrolling"}
  Full browser performance, platform scrolling behavior, and accessibility from a real horizontal scroll container.
  :::

  :::card{color="neutral" icon="i-lucide-mouse-pointer-2" title="Dragging"}
  Custom physics-based dragging for pointer input, layered on top of native scrolling instead of replacing it.
  :::

  :::card{color="neutral" icon="i-lucide-code-2" title="No abstraction"}
  Use native web APIs directly. Blossom keeps your carousel as real markup, real CSS, and real scroll state.
  :::

  :::card
  ---
  color: neutral
  icon: i-lucide-sliders-horizontal
  title: Configure with CSS
  ---
  Works with native 

  [scroll snap](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Scroll_snap){rel=""nofollow""}

  , 

  [position: sticky](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/position#sticky){rel=""nofollow""}

  , 

  [scroll-driven animations](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Scroll-driven_animations){rel=""nofollow""}

  , 

  [scroll-state queries](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Conditional_rules/Container_scroll-state_queries){rel=""nofollow""}

   and more.
  :::

  :::card{color="neutral" icon="i-lucide-feather" title="0 KB on touch devices"}
  Blossom only loads the drag enhancement when a fine pointer device is detected, so touch devices keep native scrolling untouched.
  :::

  :::card
  ---
  color: neutral
  icon: i-lucide-blocks
  title: Works with major frameworks
  ---
  Components are available for React, Vue, Svelte, and Web Components, with a framework-agnostic core package underneath.
  :::
::

## Next steps

- [Installation](https://www.blossom-carousel.com/docs/getting-started/installation) - Add Blossom Carousel to your project.
- [Examples](https://www.blossom-carousel.com/docs/examples/basic/simple) - Explore practical implementations.


# Installation

::prompt
---
actions:
  - copy
  - cursor
description: Ask my Agent to install Blossom Carousel
icon: i-lucide-square-chevron-right
---
Install Blossom Carousel in my project.

- Detect the framework I'm using (Vue or Nuxt, React or Next.js, Svelte or SvelteKit, Web Components, or standalone)
- Install Blossom Carousel with my package manager: pnpm add @blossom-carousel/ :framework[ (or npm/yarn/bun)]
- Wire up the framework-specific plugin or component

Docs: <https://www.blossom-carousel.com/start/installation>{rel=""nofollow""}
::

## Install

Install the package that matches your framework or use Blossom manually with the Core package.

::code-group{sync="migration-code-style"}
```bash [Vue]
npm install @blossom-carousel/vue
```

```bash [React]
npm install @blossom-carousel/react
```

```bash [Svelte]
npm install @blossom-carousel/svelte
```

```bash [Web]
npm install @blossom-carousel/web
```

```bash [Core]
npm install @blossom-carousel/core
```
::

## Using Agent Skills

If you use an AI assistant (Claude Code, Cursor, etc.), install the blossom-carousel skill for guided setup and code review:

::code-block
```bash [Terminal]
npx skills add https://www.blossom-carousel.com
```

## Packages

Blossom is available as framework wrappers and as a framework-agnostic core package.

  :::card-group
    ::::card
    ---
    color: neutral
    icon: i-simple-icons-vuedotjs
    title: Vue and Nuxt
    to: https://www.blossom-carousel.com/docs/framework-guides/vue-nuxt
    ---
    Start with 

    `@blossom-carousel/vue`
    ::::

    ::::card
    ---
    color: neutral
    icon: i-simple-icons-react
    title: React and Next.js
    to: https://www.blossom-carousel.com/docs/framework-guides/react-nextjs
    ---
    Start with 

    `@blossom-carousel/react`
    ::::

    ::::card
    ---
    color: neutral
    icon: i-simple-icons-svelte
    title: Svelte and SvelteKit
    to: https://www.blossom-carousel.com/docs/framework-guides/svelte-sveltekit
    ---
    Start with 

    `@blossom-carousel/svelte`
    ::::

    ::::card
    ---
    color: neutral
    icon: i-simple-icons-webcomponentsdotorg
    title: Web Components
    to: https://www.blossom-carousel.com/docs/framework-guides/web-components
    ---
    Start with 

    `@blossom-carousel/web`
    ::::

    ::::card
    ---
    color: neutral
    icon: i-lucide-braces
    title: Core
    to: https://www.blossom-carousel.com/docs/framework-guides/core
    ---
    Start with 

    `@blossom-carousel/core`
    ::::
  :::
::


# Vue and Nuxt

## Install

::code-group
```bash [pnpm]
pnpm add @blossom-carousel/vue
```

```bash [bun]
bun add @blossom-carousel/vue
```

```bash [yarn]
yarn add @blossom-carousel/vue
```

```bash [npm]
npm install @blossom-carousel/vue
```
::

## Local component usage

```vue
<script setup>
import { BlossomCarousel } from "@blossom-carousel/vue";
import "@blossom-carousel/vue/style.css";
</script>

<template>
  <BlossomCarousel>
    <div v-for="i in 12" :key="i">Slide {{ i }}</div>
  </BlossomCarousel>
</template>
```

## Nuxt plugin

Register the component globally to use it across the app.

```ts [plugins/blossom-carousel.ts]
import { BlossomCarousel } from "@blossom-carousel/vue";
import "@blossom-carousel/vue/style.css";

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.component("BlossomCarousel", BlossomCarousel);
});
```

## Semantic root element

Use `as="ul"` for list-like carousels.

```html
<BlossomCarousel as="ul">
  <li v-for="i in 12" :key="i">Slide {{ i }}</li>
</BlossomCarousel>
```

## Navigation controls

Place previous, next, and dot controls outside the carousel with `<BlossomPrev>`, `<BlossomNext>`, and `<BlossomDots>`. Link them to the carousel with an `id` on `<BlossomCarousel>`, and a matching `for` prop on each control and mark slides with `data-blossom-slide`.

```html
<BlossomCarousel id="my-carousel">
  <div v-for="i in 12" :key="i" data-blossom-slide>Slide {{ i }}</div>
</BlossomCarousel>

<BlossomPrev for="my-carousel" />
<BlossomDots for="my-carousel" />
<BlossomNext for="my-carousel" />
```

#### Prev/Next Buttons

`<BlossomPrev>` and `<BlossomNext>` are aware of configured scroll-snap and will navigate between snap points. When no scroll-snap is configured, they will slide they carousel proportionally.

Slot your own content to replace the default button icon.

```html
<BlossomPrev for="my-carousel">
  <span>Previous</span>
</BlossomPrev>
```

#### Dots

`<BlossomDots>` renders one button per slide marked with `data-blossom-slide`.
Default styles can be themed with CSS custom properties on the component or any ancestor:

```css
/* defaults */
{
  --blossom-dot-size: 0.625rem;
  --blossom-dot-radius: 50%;
  --blossom-dot-color: currentColor;
  --blossom-dot-opacity: 0.35;
  --blossom-dot-hover-opacity: 0.6;
  --blossom-dot-active-opacity: 1;
}
```

To bring your own dots, provide a default slot and render `<BlossomDot>` inside it. This will configure the dot as a `<button>` with navigation wired up.
Now you can style the dot as you please and attach any button attributes you need.

```html
<BlossomDots for="my-carousel" v-slot="{ index, active }">
  <BlossomDot
    class="my-dot"
    :data-active="active"
    :aria-label="`Photo ${index + 1}`"
  >
    {{ index + 1 }}
  </BlossomDot>
</BlossomDots>
```

#### Listening for commands

Listen for `command` events on the carousel to know when any navigation control is triggered:

- previous (`--blossom-prev`)
- next (`--blossom-next`)
- dot (`--blossom-goto-{index}`).

These events are not fired by drag or free scrolling. Read `event.command` (or `event.detail.command` where the Invoker Commands polyfill applies).

```html
<BlossomCarousel @command="handleCommand">
  <div v-for="i in 12" :key="i" data-blossom-slide>Slide {{ i }}</div>
</BlossomCarousel>

<script setup lang="ts">
  const handleCommand = (event: CustomEvent) => {
    const command = event?.command || event?.detail?.command;
  };
</script>
```

#### Global registration

Register the components alongside `BlossomCarousel`:

```javascript
import {
  BlossomCarousel,
  BlossomPrev,
  BlossomNext,
  BlossomDots,
  BlossomDot,
} from "@blossom-carousel/vue";
import "@blossom-carousel/vue/style.css";

const app = createApp({});
app.component("BlossomCarousel", BlossomCarousel);
app.component("BlossomPrev", BlossomPrev);
app.component("BlossomNext", BlossomNext);
app.component("BlossomDots", BlossomDots);
app.component("BlossomDot", BlossomDot);
```

See the [Buttons](https://www.blossom-carousel.com/docs/examples/basic/buttons) and [Dots](https://www.blossom-carousel.com/docs/examples/basic/dots) examples for live demos.

## Overscroll API

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

```vue
<template>
  <!-- prevent and overwrite Blossom's default rubberbanding effect -->
  <BlossomCarousel @overscroll.prevent="onOverscroll">
    <div v-for="i in 12" :key="i">Slide {{ i }}</div>
  </BlossomCarousel>
</template>

<script setup>
function onOverscroll(event) {
  const overScroll = event.detail.left;

  Array.from(blossomCarousel.value.children).forEach((slide) => {
    slide.style.transform = `scale(${1 - overScroll * 0.1})`;
  });
}
</script>
```


# React and Next.js

## Install

::code-group
```bash [pnpm]
pnpm add @blossom-carousel/react
```

```bash [bun]
bun add @blossom-carousel/react
```

```bash [yarn]
yarn add @blossom-carousel/react
```

```bash [npm]
npm install @blossom-carousel/react
```
::

## React usage

```tsx
import { BlossomCarousel } from "@blossom-carousel/react";
import "@blossom-carousel/react/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 stylesheet from a global entry point.

```tsx [app/layout.tsx]
import "@blossom-carousel/react/style.css";

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

Then render the carousel from a component.

```tsx [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

Use `as="ul"` for list-like carousels.

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

## Navigation controls

Place previous, next, and dot controls outside the carousel with `<BlossomPrev>`, `<BlossomNext>`, and `<BlossomDots>`. Link them to the carousel with an `id` on `<BlossomCarousel>`, and a matching `for` prop on each control and mark slides with `data-blossom-slide`.

```tsx
<BlossomCarousel id="my-carousel">
  {Array.from({ length: 12 }, (_, index) => (
    <div key={index} data-blossom-slide>
      Slide {index + 1}
    </div>
  ))}
</BlossomCarousel>

<BlossomPrev for="my-carousel" />
<BlossomDots for="my-carousel" />
<BlossomNext for="my-carousel" />
```

#### Prev/Next Buttons

`<BlossomPrev>` and `<BlossomNext>` are aware of configured scroll-snap and will navigate between snap points. When no scroll-snap is configured, they will slide the carousel proportionally.

Slot your own content to replace the default button icon.

```tsx
<BlossomPrev for="my-carousel">
  <span>Previous</span>
</BlossomPrev>;
```

#### Dots

`<BlossomDots>` renders one button per slide marked with `data-blossom-slide`.
Default styles can be themed with CSS custom properties on the component or any ancestor:

```css
/* defaults */
{
  --blossom-dot-size: 0.625rem;
  --blossom-dot-radius: 50%;
  --blossom-dot-color: currentColor;
  --blossom-dot-opacity: 0.35;
  --blossom-dot-hover-opacity: 0.6;
  --blossom-dot-active-opacity: 1;
}
```

To bring your own dots, provide a default slot and render `<BlossomDot>` inside it. This will configure the dot as a `<button>` with navigation wired up.
Now you can style the dot as you please and attach any button attributes you need.

```tsx
<BlossomDots for="my-carousel">
  {({ index, active }) => (
    <BlossomDot
      className="my-dot"
      data-active={active}
      aria-label={`Photo ${index + 1}`}
    >
      {index + 1}
    </BlossomDot>
  )}
</BlossomDots>;
```

#### Listening for commands

Listen for `command` events on the carousel to know when any navigation control is triggered:

- previous (`--blossom-prev`)
- next (`--blossom-next`)
- dot (`--blossom-goto-{index}`).

These events are not fired by drag or free scrolling. Read `event.command` (or `event.detail.command` where the Invoker Commands polyfill applies).

```tsx
<BlossomCarousel onCommand={handleCommand}>
  {Array.from({ length: 12 }, (_, index) => (
    <div key={index} data-blossom-slide>
      Slide {index + 1}
    </div>
  ))}
</BlossomCarousel>;

function handleCommand(event: CustomEvent) {
  const command = event?.command || event?.detail?.command;
}
```

See the [Buttons](https://www.blossom-carousel.com/docs/examples/basic/buttons) and [Dots](https://www.blossom-carousel.com/docs/examples/basic/dots) examples for live demos.

## Overscroll API

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

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


# Svelte and SvelteKit

## Install

::code-group
```bash [pnpm]
pnpm add @blossom-carousel/svelte
```

```bash [bun]
bun add @blossom-carousel/svelte
```

```bash [yarn]
yarn add @blossom-carousel/svelte
```

```bash [npm]
npm install @blossom-carousel/svelte
```
::

## Svelte usage

::note{color="neutral" icon="i-lucide-lightbulb"}
`@blossom-carousel/svelte`

 

`2.x`

 requires Svelte 5 (runes + snippets) and drops Svelte 4 support. If you're on Svelte 4, stay on 

`@blossom-carousel/svelte@1`

.
::

```svelte
<script>
  import { BlossomCarousel } from "@blossom-carousel/svelte";
  import "@blossom-carousel/svelte/style.css";

  const slides = Array.from({ length: 12 }, (_, index) => index + 1);
</script>

<BlossomCarousel>
  {#each slides as slide (slide)}
    <div>Slide {slide}</div>
  {/each}
</BlossomCarousel>
```

## SvelteKit setup

Import the stylesheet from the root layout.

```svelte [src/routes/+layout.svelte]
<script>
  import "@blossom-carousel/svelte/style.css";

  let { children } = $props();
</script>

{@render children()}
```

Then import the component in the page or component that renders the carousel.

```svelte
<script>
  import { BlossomCarousel } from "@blossom-carousel/svelte";
</script>

<BlossomCarousel>{/* slides */}</BlossomCarousel>
```

## Semantic root element

Use `as="ul"` for list-like carousels.

```svelte
<BlossomCarousel as="ul">
  {#each slides as slide (slide)}
    <li>Slide {slide}</li>
  {/each}
</BlossomCarousel>
```

## Navigation controls

Place previous, next, and dot controls outside the carousel with `<BlossomPrev>`, `<BlossomNext>`, and `<BlossomDots>`. Link them to the carousel with an `id` on `<BlossomCarousel>`, and a matching `forId` prop on each control and mark slides with `data-blossom-slide`.

```svelte
<BlossomCarousel id="my-carousel">
  {#each slides as slide (slide)}
    <div data-blossom-slide>Slide {slide}</div>
  {/each}
</BlossomCarousel>

<BlossomPrev forId="my-carousel" />
<BlossomDots forId="my-carousel" />
<BlossomNext forId="my-carousel" />
```

::note{color="neutral" icon="i-lucide-lightbulb"}
Place navigation components 

*after*

 their carousel in the markup, as above. 

`BlossomDots`

 renders one button per marked slide server-side, before any client JS runs, by reading the slide count that 

`BlossomCarousel`

 registers when it renders. Controls placed before the carousel start at zero dots and fill in on the client.
::

#### Prev/Next Buttons

`<BlossomPrev>` and `<BlossomNext>` are aware of configured scroll-snap and will navigate between snap points. When no scroll-snap is configured, they will slide the carousel proportionally.

Slot your own content to replace the default button icon.

```svelte
<BlossomPrev forId="my-carousel">
  <span>Previous</span>
</BlossomPrev>
```

#### Dots

`<BlossomDots>` renders one button per slide marked with `data-blossom-slide`.
Default styles can be themed with CSS custom properties on the component or any ancestor:

```css
/* defaults */
{
  --blossom-dot-size: 0.625rem;
  --blossom-dot-radius: 50%;
  --blossom-dot-color: currentColor;
  --blossom-dot-opacity: 0.35;
  --blossom-dot-hover-opacity: 0.6;
  --blossom-dot-active-opacity: 1;
}
```

To bring your own dots, provide a default slot and render `<BlossomDot>` inside it. This will configure the dot as a `<button>` with navigation wired up.
Now you can style the dot as you please and attach any button attributes you need.

```svelte
<BlossomDots forId="my-carousel">
  {#snippet children({ index, active })}
    <BlossomDot
      class="my-dot"
      data-active={active}
      aria-label="Photo {index + 1}"
    >
      {index + 1}
    </BlossomDot>
  {/snippet}
</BlossomDots>
```

#### Listening for commands

Listen for `command` events on the carousel to know when any navigation control is triggered:

- previous (`--blossom-prev`)
- next (`--blossom-next`)
- dot (`--blossom-goto-{index}`).

These events are not fired by drag or free scrolling. Read `event.command` (or `event.detail.command` where the Invoker Commands polyfill applies).

```svelte
<script>
  function handleCommand(event) {
    const command = event?.command || event?.detail?.command;
  }
</script>

<BlossomCarousel oncommand={handleCommand}>
  {#each slides as slide (slide)}
    <div data-blossom-slide>Slide {slide}</div>
  {/each}
</BlossomCarousel>
```

See the [Buttons](https://www.blossom-carousel.com/docs/examples/basic/buttons) and [Dots](https://www.blossom-carousel.com/docs/examples/basic/dots) examples for live demos.

## Overscroll API

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

```svelte
<script>
  function onOverscroll(event) {
    // prevent and overwrite Blossom's default rubberbanding effect
    event.preventDefault();

    const overScroll = event.detail.left;

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

<BlossomCarousel onoverscroll={onOverscroll}>
  {#each Array.from({ length: 12 }, (_, index) => index + 1) as slide (slide)}
    <div>Slide {slide}</div>
  {/each}
</BlossomCarousel>
```

::note{color="neutral" icon="i-lucide-lightbulb"}
`BlossomCarousel`

 forwards unrecognized props to its root element, so 

`onoverscroll`

 attaches directly via 

`addEventListener`

. There's no exposed ref to the root DOM node, so read the target off the event (

`event.target`

) rather than binding a ref.
::


# Web Components

## Install

::code-group
```bash [pnpm]
pnpm add @blossom-carousel/web
```

```bash [bun]
bun add @blossom-carousel/web
```

```bash [yarn]
yarn add @blossom-carousel/web
```

```bash [npm]
npm install @blossom-carousel/web
```
::

## Module setup

```js
import "@blossom-carousel/web";
import "@blossom-carousel/web/style.css";
```

After the module is imported, the `<blossom-carousel>` element is registered.

```html
<blossom-carousel class="carousel">
  <div class="slide">Slide 1</div>
  <div class="slide">Slide 2</div>
  <div class="slide">Slide 3</div>
</blossom-carousel>
```

## CDN setup

```html
<script
  defer
  src="https://unpkg.com/@blossom-carousel/web/dist/blossom-carousel-web.umd.js"
></script>
<link
  rel="stylesheet"
  href="https://unpkg.com/@blossom-carousel/web/dist/blossom-carousel-web.css"
/>
```

Use the CDN build for static pages without a build step.

### Navigation controls

Place previous, next, and dot controls outside the carousel with `<blossom-prev>`, `<blossom-next>`, and `<blossom-dots>`. Link them to the carousel with an `id` on `<blossom-carousel>`, and a matching `for` attribute on each control and mark slides with `data-blossom-slide`.

```html
<blossom-carousel id="my-carousel">
  <div data-blossom-slide>Slide 1</div>
  <div data-blossom-slide>Slide 2</div>
  <div data-blossom-slide>Slide 3</div>
  ...
</blossom-carousel>

<blossom-prev for="my-carousel"></blossom-prev>
<blossom-dots for="my-carousel"></blossom-dots>
<blossom-next for="my-carousel"></blossom-next>
```

#### Prev/Next Buttons

`<blossom-prev>` and `<blossom-next>` are aware of configured scroll-snap and will navigate between snap points. When no scroll-snap is configured, they will slide the carousel proportionally.

Slot your own content to replace the default button icon.

```html
<blossom-prev for="my-carousel">
  <span>Previous</span>
</blossom-prev>
```

#### Dots

`<blossom-dots>` renders one button per slide marked with `data-blossom-slide`.
Default styles can be themed with CSS custom properties on the component or any ancestor:

```css
/* defaults */
{
  --blossom-dot-size: 0.625rem;
  --blossom-dot-radius: 50%;
  --blossom-dot-color: currentColor;
  --blossom-dot-opacity: 0.35;
  --blossom-dot-hover-opacity: 0.6;
  --blossom-dot-active-opacity: 1;
}
```

To bring your own dots, provide a `<blossom-dot>` child — it is cloned for each slide and its inner `<button>` receives navigation attributes automatically.

```html
<blossom-dots for="my-carousel">
  <blossom-dot class="my-dot">
    <button type="button" aria-label="Custom label">•</button>
  </blossom-dot>
</blossom-dots>
```

Or let `blossom-dot` create the button from its light-DOM children:

```html
<blossom-dots for="my-carousel">
  <blossom-dot class="my-dot">•</blossom-dot>
</blossom-dots>
```

The prototype `<blossom-dot>` stays hidden; clones are rendered in the dots container. Existing `aria-label` and other attributes on your button are preserved. Since it's a single cloned template, every dot gets identical content — fine for a single active/inactive look, but not for content that varies per slide (e.g. per-slide thumbnails).

For that, set `renderDot` on the `blossom-dots` element — a callback invoked once per slide with `(index, active, forId)`. It takes priority over any `<blossom-dot>` prototype and returns the element to render; navigation attributes are merged onto its `<button>` automatically:

```html
<blossom-dots for="my-carousel" id="dots"></blossom-dots>

<script type="module">
  document.getElementById("dots").renderDot = (index, active) => {
    const button = document.createElement("button");
    button.setAttribute("data-blossom-dot", "");
    button.className = "dot";
    button.dataset.active = String(active);
    button.innerHTML = `<img src="/thumbs/${index}.jpg" alt="Slide ${index + 1}">`;
    return button;
  };
</script>
```

See the [Buttons](https://www.blossom-carousel.com/docs/examples/basic/buttons) and [Dots](https://www.blossom-carousel.com/docs/examples/basic/dots) examples for live demos.

#### Listening for commands

Listen for `command` events on the carousel to know when any navigation control is triggered:

- previous (`--blossom-prev`)
- next (`--blossom-next`)
- dot (`--blossom-goto-{index}`).

These events are not fired by drag or free scrolling. Read `event.command` (or `event.detail.command` where the Invoker Commands polyfill applies).

```html
<blossom-carousel id="my-carousel">
  <div data-blossom-slide>Slide 1</div>
  <div data-blossom-slide>Slide 2</div>
  <div data-blossom-slide>Slide 3</div>
</blossom-carousel>

<script>
  document
    .getElementById("my-carousel")
    .addEventListener("command", (event) => {
      const command = event?.command || event?.detail?.command;
    });
</script>
```

## Overscroll API

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

```html
<blossom-carousel id="my-carousel">
  <div>Slide 1</div>
  <div>Slide 2</div>
  <div>Slide 3</div>
</blossom-carousel>

<script>
  document
    .getElementById("my-carousel")
    .addEventListener("overscroll", (event) => {
      event.preventDefault();
      const overScroll = event.detail.left;

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


# Core

## Install

::code-group
```bash [pnpm]
pnpm add @blossom-carousel/core
```

```bash [bun]
bun add @blossom-carousel/core
```

```bash [yarn]
yarn add @blossom-carousel/core
```

```bash [npm]
npm install @blossom-carousel/core
```
::

## Basic setup

```js
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.

```js
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();
}
```

## Destroy

```js
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.

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

  const overScroll = event.detail.left;

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


# Simple

:example-simple

::tabs{sync="example-code-style"}
  :::tabs-item{label="CSS"}
    ::::code-group
    ```css [.css]
    .carousel {
      display: grid;
      grid-auto-flow: column;
      grid-auto-columns: 200px;
      gap: 1rem;
    }

    .slide {
      width: 100%;
      aspect-ratio: 3 / 4;
    }
    ```

    ```html [.html]
    <BlossomCarousel class="carousel">
      <div class="slide"></div>
      <div class="slide"></div>
      <div class="slide"></div>
      ...
    </BlossomCarousel>
    ```
    ::::
  :::

  :::tabs-item{label="Tailwind"}
  ```html [.html]
  <BlossomCarousel class="grid auto-cols-[200px] grid-flow-col gap-4">
    <div class="w-full aspect-3/4"></div>
    <div class="w-full aspect-3/4"></div>
    <div class="w-full aspect-3/4"></div>
    ...
  </BlossomCarousel>
  ```
  :::
::


# Snapping

:example-snapping

::tabs{sync="example-code-style"}
  :::tabs-item{label="CSS"}
    ::::code-group
    ```css [.css]
    .carousel {
      display: grid;
      grid-auto-flow: column;
      grid-auto-columns: 200px;
      gap: 1rem;
      scroll-snap-type: inline mandatory;
    }

    .slide {
      width: 100%;
      aspect-ratio: 3 / 4;
      scroll-snap-align: center;
    }
    ```

    ```html [.html]
    <BlossomCarousel class="carousel">
      <div class="slide"></div>
      <div class="slide"></div>
      <div class="slide"></div>
      ...
    </BlossomCarousel>
    ```
    ::::
  :::

  :::tabs-item{label="Tailwind"}
  ```html [.html]
  <BlossomCarousel
    class="grid auto-cols-[200px] snap-x snap-mandatory grid-flow-col gap-4"
  >
    <div class="w-full aspect-3/4 snap-center"></div>
    <div class="w-full aspect-3/4 snap-center"></div>
    <div class="w-full aspect-3/4 snap-center"></div>
    ...
  </BlossomCarousel>
  ```
  :::
::


# Masonry

:example-masonry

::tabs{sync="example-code-style"}
  :::tabs-item{label="CSS"}
    ::::code-group
    ```css [.css]
    .carousel {
      display: grid;
      grid-auto-columns: 200px;
      grid-template-rows: repeat(3, 1fr);
      grid-auto-flow: column dense;
      gap: 1rem;
      scroll-snap-type: x mandatory;
    }

    .slide {
      &:nth-child(3n + 2) {
        grid-column: span 2;
      }

      &:nth-child(4n + 1) {
        scroll-snap-align: center;
        background-color: var(--color-primary);
      }

      &:nth-child(1),
      &:nth-child(6),
      &:nth-child(13) {
        grid-row: span 2;
      }
    }
    ```

    ```html [.html]
    <BlossomCarousel class="carousel">
      <div class="slide"></div>
      <div class="slide"></div>
      <div class="slide"></div>
      ...
    </BlossomCarousel>
    ```
    ::::
  :::

  :::tabs-item{label="Tailwind"}
  ```html [.html]
  <BlossomCarousel
    class="grid! auto-cols-[200px] h-[266px] snap-x snap-mandatory grid-rows-3 grid-flow-col grid-flow-col-dense gap-4"
  >
    <div
      class="slide size-full nth-[3n+2]:col-span-2 nth-[4n+1]:snap-center nth-[1]:row-span-2 nth-[6]:row-span-2 nth-[13]:row-span-2"
    >
      1
    </div>
    ...
  </BlossomCarousel>
  ```
  :::
::


# Right to Left

:example-right-to-left

::tabs{sync="example-code-style"}
  :::tabs-item{label="CSS"}
    ::::code-group
    ```css [.css]
    .carousel {
      display: grid;
      grid-auto-flow: column;
      grid-auto-columns: 200px;
      gap: 1rem;
    }

    .slide {
      width: 100%;
      aspect-ratio: 3 / 4;
    }
    ```

    ```html [.html]
    <BlossomCarousel dir="rtl" class="carousel">
      <div class="slide"></div>
      <div class="slide"></div>
      <div class="slide"></div>
      ...
    </BlossomCarousel>
    ```
    ::::
  :::

  :::tabs-item{label="Tailwind"}
  ```html [.html]
  <BlossomCarousel dir="rtl" class="grid auto-cols-[200px] grid-flow-col gap-4">
    <div class="w-full aspect-3/4"></div>
    <div class="w-full aspect-3/4"></div>
    <div class="w-full aspect-3/4"></div>
    ...
  </BlossomCarousel>
  ```
  :::
::


# Sticky Slides

:example-sticky

::tabs{sync="example-code-style"}
  :::tabs-item{label="CSS"}
    ::::code-group
    ```css [.css]
    .carousel {
      display: grid;
      grid-auto-flow: column;
      grid-auto-columns: 100%;
      gap: 1rem;
      height: 22.5rem;
    }

    .slide {
      display: grid;
      grid-template-rows: 1fr auto;
      gap: 0.5rem;
    }

    .card {
      width: 100%;
      height: 100%;
    }

    .label {
      position: sticky;
      left: 0;
      width: fit-content;
    }
    ```

    ```html [.html]
    <BlossomCarousel class="carousel">
      <div class="slide">
        <div class="card"></div>
        <p class="label">Slide 01</p>
      </div>
      <div class="slide">
        <div class="card"></div>
        <p class="label">Slide 02</p>
      </div>
      ...
    </BlossomCarousel>
    ```
    ::::
  :::

  :::tabs-item{label="Tailwind"}
  ```html [.html]
  <BlossomCarousel class="grid! auto-cols-[100%] grid-flow-col gap-4 h-90">
    <div class="grid! grid-rows-[1fr_auto] gap-2 size-full">
      <div class="size-full"></div>
      <p class="sticky left-0 w-fit px-2">Slide 01</p>
    </div>
    <div class="grid! grid-rows-[1fr_auto] gap-2 size-full">
      <div class="size-full"></div>
      <p class="sticky left-0 w-fit px-2">Slide 02</p>
    </div>
    ...
  </BlossomCarousel>
  ```
  :::
::


# Buttons

:example-buttons

::tabs{sync="example-code-style"}
  :::tabs-item{label="CSS"}
  ```html [.html]
  <BlossomCarousel id="gallery" class="carousel">
    <div class="slide"></div>
    <div class="slide"></div>
    <div class="slide"></div>
    ...
  </BlossomCarousel>

  <div class="controls">
    <BlossomPrev for="gallery" />
    <BlossomNext for="gallery" />
  </div>
  ```

  ```css [.css]
  .carousel {
    display: grid;
    grid-auto-flow: column;
    grid-auto-columns: 200px;
    gap: 1rem;
    scroll-snap-type: inline mandatory;
  }

  .slide {
    width: 100%;
    aspect-ratio: 3 / 4;
    scroll-snap-align: center;
  }

  .controls {
    display: flex;
    gap: 1rem;
  }
  ```
  :::

  :::tabs-item{label="Tailwind"}
  ```html [.html]
  <BlossomCarousel id="gallery" class="grid auto-cols-[200px] snap-x snap-mandatory grid-flow-col gap-4">
    <div class="w-full aspect-3/4 snap-center"></div>
    <div class="w-full aspect-3/4 snap-center"></div>
    <div class="w-full aspect-3/4 snap-center"></div>
    ...
  </BlossomCarousel>

  <div class="flex gap-4">
    <BlossomPrev for="gallery" />
    <BlossomNext for="gallery" />
  </div>
  ```
  :::
::


# Dots

:example-dots

::tabs{sync="example-code-style"}
  :::tabs-item{label="CSS"}
  ```html [.html]
  <BlossomCarousel id="gallery" class="carousel">
    <div data-blossom-slide class="slide"></div>
    <div data-blossom-slide class="slide"></div>
    <div data-blossom-slide class="slide"></div>
    ...
  </BlossomCarousel>

  <BlossomDots for="gallery" />
  ```

  ```css [.css]
  .carousel {
    display: grid;
    grid-auto-flow: column;
    grid-auto-columns: 100%;
    gap: 1rem;
    scroll-snap-type: x mandatory;
    height: 22.5rem;
  }

  .slide {
    width: 100%;
    scroll-snap-align: center;
  }
  ```
  :::

  :::tabs-item{label="Tailwind"}
  ```html [.html]
  <BlossomCarousel
    id="gallery"
    class="grid auto-cols-[200px] grid-flow-col gap-4"
  >
    <div data-blossom-slide class="w-full aspect-3/4"></div>
    <div data-blossom-slide class="w-full aspect-3/4"></div>
    <div data-blossom-slide class="w-full aspect-3/4"></div>
    ...
  </BlossomCarousel>

  <BlossomDots for="gallery" />
  ```
  :::
::


# Thumbnails

:example-thumbnails

::tabs
  :::tabs-item{label="Vue"}
  ```vue-html [.vue]
  <BlossomCarousel id="gallery" class="grid auto-cols-[100%] aspect-square snap-x snap-mandatory grid-flow-col">
    <div v-for="image in images" :key="image" data-blossom-slide class="w-full snap-center">
      <img :src="image" />
    </div>
  </BlossomCarousel>

  <BlossomDots for="gallery" class="flex flex-col gap-1">
    <template #default="{ index, active }">
      <BlossomDot :data-active="active">
        <img :src="images[index]" />
      </BlossomDot>
    </template>
  </BlossomDots>
  ```
  :::

  :::tabs-item{label="React"}
  ```tsx [.tsx]
  <BlossomCarousel id="gallery" className="grid auto-cols-[100%] aspect-square snap-x snap-mandatory grid-flow-col">
    {images.map((_, index) => (
      <div key={index} data-blossom-slide className="w-full snap-center">
        <img src={images[index]} />
      </div>
    ))}
  </BlossomCarousel>

  <BlossomDots for="gallery" className="flex flex-col gap-1">
    {({ index, active }) => (
      <BlossomDot data-active={active}>
        <img src={images[index]} />
      </BlossomDot>
    )}
  </BlossomDots>
  ```
  :::

  :::tabs-item{label="Svelte"}
  ```svelte [.svelte]
  <BlossomCarousel id="gallery" class="grid auto-cols-[100%] aspect-square snap-x snap-mandatory grid-flow-col">
    {#each images as image, index (image)}
      <div data-blossom-slide class="w-full snap-center">
        <img src={image} />
      </div>
    {/each}
  </BlossomCarousel>

  <BlossomDots forId="gallery" class="flex flex-col gap-1">
    {#snippet children({ index, active })}
      <BlossomDot data-active={active}>
        <img src={images[index]} />
      </BlossomDot>
    {/snippet}
  </BlossomDots>
  ```
  :::
::


# Cover Flow

::supports-view-timeline-support
  :::caution
  View-timeline is not yet supported in this browser. Check browser compatibility at 

  [caniuse.com](https://caniuse.com/?search=scroll-snap-change){rel=""nofollow""}
  :::
::

:example-cover-flow

::tabs{sync="example-code-style"}
  :::tabs-item{label="CSS"}
    ::::code-group
    ```css [.css]
    .carousel {
      padding-inline: calc(50% - 50px);
      scroll-snap-type: x mandatory;
    }

    ul {
      white-space: nowrap;
      transform-style: preserve-3d;
    }

    li {
      display: inline-block;
      position: relative;
      width: 100px;
      aspect-ratio: 1 / 2;
      transform-style: preserve-3d;
      scroll-snap-align: center;

      view-timeline: --slide inline calc(50% - 140px);
    }

    .slide {
      perspective: 500px;
      position: absolute;
      top: 0;
      left: -50%;
      width: 200%;
      aspect-ratio: 1;
      transform-style: preserve-3d;

      animation: linear slide-cover both;
      animation-timeline: --slide;
      animation-range: contain;
    }

    .card {
      width: 100%;
      height: 100%;

      animation: linear rotate-cover both;
      animation-timeline: --slide;
      animation-range: contain;
    }

    @keyframes rotate-cover {
      0% {
        transform: rotateY(-55deg);
      }
      50% {
        transform: rotateY(0deg);
      }
      100% {
        transform: rotateY(55deg);
      }
    }

    @keyframes slide-cover {
      0% {
        transform: translateX(30%);
      }
      50% {
        transform: translateX(0) scale(1.2);
      }
      100% {
        transform: translateX(-30%);
      }
    }
    ```

    ```html [.html]
    <BlossomCarousel class="carousel">
      <ul>
        <li>
          <div class="slide">
            <div class="card"></div>
          </div>
        </li>
        <li>
          <div class="slide">
            <div class="card"></div>
          </div>
        </li>
        ...
      </ul>
    </BlossomCarousel>
    ```
    ::::
  :::

  :::tabs-item{label="Tailwind"}
    ::::code-group
    ```css [.css]
    li {
      view-timeline: --slide inline calc(50% - 140px);
    }

    .slide {
      animation: linear slide-cover both;
      animation-timeline: --slide;
      animation-range: contain;
    }

    .card {
      animation: linear rotate-cover both;
      animation-timeline: --slide;
      animation-range: contain;
    }

    @keyframes rotate-cover {
      0% {
        transform: rotateY(-55deg);
      }
      50% {
        transform: rotateY(0deg);
      }
      100% {
        transform: rotateY(55deg);
      }
    }

    @keyframes slide-cover {
      0% {
        transform: translateX(30%);
      }
      50% {
        transform: translateX(0) scale(1.2);
      }
      100% {
        transform: translateX(-30%);
      }
    }
    ```

    ```html [.html]
    <BlossomCarousel class="py-24 snap-x snap-mandatory px-[calc(50%-50px)]!">
      <ul class="whitespace-nowrap! transform-3d">
        <li
          v-for="i in 12"
          :key="i"
          class="inline-block! relative transform-3d snap-center w-[100px] aspect-1/2 even:*:*:bg-primary-400"
        >
          <div
            class="perspective-normal slide absolute transform-3d top-0 -left-1/2 aspect-square w-[200%]"
          >
            <div
              class="card bg-primary rounded-lg flex items-center justify-center text-2xl font-bold text-white size-full"
            >
              {{ i }}
            </div>
          </div>
        </li>
      </ul>
    </BlossomCarousel>
    ```
    ::::
  :::
::


# Slideshow

::supports-view-timeline-support
  :::caution
  View-timeline is not yet supported in this browser. Check browser compatibility at 

  [caniuse.com](https://caniuse.com/?search=scroll-snap-change){rel=""nofollow""}
  :::
::

:example-slideshow

::tabs{sync="example-code-style"}
  :::tabs-item{label="CSS"}
    ::::code-group
    ```css [.css]
    .carousel {
      display: grid;
      grid-auto-flow: column;
      grid-auto-columns: 100%;
      scroll-snap-type: x mandatory;
      height: 22.5rem;
    }

    .slide {
      width: 100%;
      height: 100%;
      overflow: hidden;
      scroll-snap-align: center;

      view-timeline: --slide inline;
    }

    .slide .card {
      width: 100%;
      height: 100%;

      animation: parallax linear both;
      animation-timeline: --slide;
      animation-range: cover;
    }

    @keyframes parallax {
      0% {
        transform: translateX(-50%);
      }
      50% {
        transform: translateX(0%);
      }
      100% {
        transform: translateX(50%);
      }
    }
    ```

    ```html [.html]
    <BlossomCarousel class="carousel">
      <div class="slide">
        <div class="card"></div>
      </div>
      <div class="slide">
        <div class="card"></div>
      </div>
      <div class="slide">
        <div class="card"></div>
      </div>
      ...
    </BlossomCarousel>
    ```
    ::::
  :::

  :::tabs-item{label="Tailwind"}
    ::::code-group
    ```css [.css]
    .slide {
      view-timeline: --slide inline;
    }

    .slide .card {
      animation: parallax linear both;
      animation-timeline: --slide;
      animation-range: cover;
    }

    @keyframes parallax {
      0% {
        transform: translateX(-50%);
      }
      50% {
        transform: translateX(0%);
      }
      100% {
        transform: translateX(50%);
      }
    }
    ```

    ```html [.html]
    <BlossomCarousel
      class="grid! h-90 snap-x snap-mandatory auto-cols-[100%] grid-flow-col"
    >
      <div class="slide size-full overflow-hidden snap-center">
        <div class="card size-full"></div>
      </div>
      <div class="slide size-full overflow-hidden snap-center">
        <div class="card size-full"></div>
      </div>
      <div class="slide size-full overflow-hidden snap-center">
        <div class="card size-full"></div>
      </div>
      ...
    </BlossomCarousel>
    ```
    ::::
  :::
::


# Stories

::supports-view-timeline-support
  :::caution
  View-timeline is not yet supported in this browser. Check browser compatibility at 

  [caniuse.com](https://caniuse.com/?search=scroll-snap-change){rel=""nofollow""}
  :::
::

:example-stories

::tabs{sync="example-code-style"}
  :::tabs-item{label="CSS"}
    ::::code-group
    ```css [.css]
    .frame {
      aspect-ratio: 9 / 16;
      width: 100%;
      max-width: 20rem;
      perspective: 1200px;
      overflow: clip;
    }

    .carousel {
      display: grid;
      grid-auto-flow: column;
      grid-auto-columns: 100%;
      scroll-snap-type: x mandatory;
      height: 100%;
    }

    .slide {
      width: 100%;
      height: 100%;
      scroll-snap-align: center;
      scroll-snap-stop: always;
      perspective: 1200px;

      view-timeline: --stories inline;
    }

    .slide .card {
      width: 100%;
      height: 100%;

      animation: stories linear both;
      animation-timeline: --stories;
      animation-range: cover;
    }

    @keyframes stories {
      0% {
        transform: rotateY(90deg);
        transform-origin: left center;
      }
      49% {
        transform: rotateY(0deg);
        transform-origin: left center;
      }
      50% {
        transform: rotateY(0deg);
        transform-origin: center center;
      }
      51% {
        transform: rotateY(0deg);
        transform-origin: right center;
      }
      100% {
        transform: rotateY(-90deg);
        transform-origin: right center;
      }
    }
    ```

    ```html [.html]
    <div class="frame">
      <BlossomCarousel class="carousel">
        <div class="slide">
          <div class="card"></div>
        </div>
        <div class="slide">
          <div class="card"></div>
        </div>
        <div class="slide">
          <div class="card"></div>
        </div>
        ...
      </BlossomCarousel>
    </div>
    ```

    ```ts [.ts]
    carousel.addEventListener("overscroll", (event: CustomEvent) => {
      const overscroll = event.detail.left;
      event.target.style.transformOrigin =
        overscroll > 0 ? "left center" : "right center";
      event.target.style.transform = `translateX(${overscroll}px) rotateY(${(overscroll / event.target.clientWidth) * 70}deg)`;
    });
    ```
    ::::
  :::

  :::tabs-item{label="Tailwind"}
    ::::code-group
    ```css [.css]
    .slide {
      view-timeline: --stories inline;
    }

    .slide .card {
      animation: stories linear both;
      animation-timeline: --stories;
      animation-range: cover;
    }

    @keyframes stories {
      0% {
        transform: rotateY(90deg);
        transform-origin: left center;
      }
      49% {
        transform: rotateY(0deg);
        transform-origin: left center;
      }
      50% {
        transform: rotateY(0deg);
        transform-origin: center center;
      }
      51% {
        transform: rotateY(0deg);
        transform-origin: right center;
      }
      100% {
        transform: rotateY(-90deg);
        transform-origin: right center;
      }
    }
    ```

    ```html [.html]
    <div class="aspect-[9/16] w-full max-w-80 perspective-normal overflow-clip">
      <BlossomCarousel
        class="grid! h-full snap-x snap-mandatory auto-cols-[100%] grid-flow-col"
      >
        <div class="slide perspective-normal size-full snap-center snap-always">
          <div class="card size-full"></div>
        </div>
        <div class="slide perspective-normal size-full snap-center snap-always">
          <div class="card size-full"></div>
        </div>
        <div class="slide perspective-normal size-full snap-center snap-always">
          <div class="card size-full"></div>
        </div>
        ...
      </BlossomCarousel>
    </div>
    ```

    ```ts [.ts]
    carousel.addEventListener("overscroll", (event: CustomEvent) => {
      const overscroll = event.detail.left;
      event.target.style.transformOrigin =
        overscroll > 0 ? "left center" : "right center";
      event.target.style.transform = `translateX(${overscroll}px) rotateY(${(overscroll / event.target.clientWidth) * 70}deg)`;
    });
    ```
    ::::
  :::
::


# Smart Stack

::supports-view-timeline-support
  :::caution
  View-timeline is not yet supported in this browser. Check browser compatibility at 

  [caniuse.com](https://caniuse.com/?search=scroll-snap-change){rel=""nofollow""}
  :::
::

:example-smart-stack

::tabs{sync="example-code-style"}
  :::tabs-item{label="CSS"}
    ::::code-group
    ```css [.css]
    .widget {
      width: 160px;
      height: 160px;
      overflow: clip;
      background: red;
      border-radius: 2rem;
    }

    .smart-stack {
      display: grid;
      grid-auto-flow: column;
      grid-auto-columns: 100%;
      height: 100%;
      scroll-snap-type: x mandatory;

      & .slide {
        view-timeline: --slide inline 30%;

        & .slide-content {
          animation: slide cubic-bezier(0, 0.5, 1, 0.5) both;
          animation-timeline: --slide;
          animation-range: cover;
        }
      }
    }

    .slide {
      width: 100%;
      height: 100%;
      scroll-snap-align: center;
      scroll-snap-stop: always;
    }

    .slide-content {
      width: 100%;
      height: 100%;
      background: blue;
      border-radius: 2rem;
    }

    @keyframes slide {
      0% {
        scale: 0.8;
      }
      50% {
        scale: 1;
      }
      100% {
        scale: 0.8;
      }
    }
    ```

    ```html [.html]
    <div class="widget">
      <BlossomCarousel class="smart-stack">
        <div class="slide">
          <div class="slide-content"></div>
        </div>
        <div class="slide">
          <div class="slide-content"></div>
        </div>
        <div class="slide">
          <div class="slide-content"></div>
        </div>
        ...
      </BlossomCarousel>
    </div>
    ```
    ::::
  :::

  :::tabs-item{label="Tailwind"}
    ::::code-group
    ```css [.css]
    .smart-stack {
      & .slide {
        view-timeline: --slide inline 30%;

        & .slide-content {
          animation: slide cubic-bezier(0, 0.5, 1, 0.5) both;
          animation-timeline: --slide;
          animation-range: cover;
        }
      }
    }

    @keyframes slide {
      0% {
        scale: 0.8;
      }
      50% {
        scale: 1;
      }
      100% {
        scale: 0.8;
      }
    }
    ```

    ```html [.html]
    <div class="size-40 aspect-square overflow-clip bg-primary/30 rounded-xl">
      <BlossomCarousel
        class="smart-stack snap-x snap-mandatory grid! grid-flow-col auto-cols-[100%] h-full"
      >
        <div class="size-full snap-center snap-always">
          <div class="size-full rounded-lg bg-primary rounded-xl"></div>
        </div>
        <div class="size-full snap-center snap-always">
          <div class="size-full rounded-lg bg-primary rounded-xl"></div>
        </div>
        <div class="size-full snap-center snap-always">
          <div class="size-full rounded-lg bg-primary rounded-xl"></div>
        </div>
        ...
      </BlossomCarousel>
    </div>
    ```
    ::::
  :::
::


# Cards

::supports-view-timeline-support
  :::caution
  View-timeline is not yet supported in this browser. Check browser compatibility at 

  [caniuse.com](https://caniuse.com/?search=scroll-snap-change){rel=""nofollow""}
  :::
::

::supports-view-timeline-safari-support
  :::caution
  Safari's 

  `view-timeline`

   implementation does not yet account for sticky offsets when calculating 

  `animation-range: contain`

  , so scroll-driven animations in this example appear incorrect. See 

  [WebKit bug 288913](https://bugs.webkit.org/show_bug.cgi?id=288913){rel=""nofollow""}

  .
  :::
::

:example-cards

::tabs{sync="example-code-style"}
  :::tabs-item{label="CSS"}
    ::::code-group
    ```css [.css]
    .carousel {
      --card-width: 12rem;
      display: grid;
      grid-auto-flow: column;
      grid-auto-columns: 100%;
      scroll-snap-type: x mandatory;
      width: calc(var(--card-width) * 3);
      padding-inline: var(--card-width);
    }

    .slide {
      width: var(--card-width);
      aspect-ratio: 3 / 4;
      position: sticky;
      left: calc(var(--card-width) * -1);
      right: calc(var(--card-width) * -1);

      scroll-snap-align: center;
      scroll-snap-stop: always;

      transform-origin: center 70%;
      will-change: transform;

      view-timeline: --cards inline;
      animation: stack-cards linear both;
      animation-timeline: --cards;
      animation-range: contain;

      & .card {
        width: 100%;
        height: 100%;

        animation: rotate-cards linear both;
        animation-timeline: --cards;
        animation-range: contain -50% contain 150%;
      }
    }

    @keyframes stack-cards {
      0% {
        z-index: calc(100 - sibling-index());
      }
      40% {
        z-index: 1000;
      }
      100% {
        z-index: sibling-index();
      }
    }

    @keyframes rotate-cards {
      0% {
        transform: translateX(-80%) rotate(10deg) scale(0.8);
      }
      25% {
        transform: translateX(-90%) rotate(5deg) scale(0.9);
      }
      50% {
        transform: translateX(0%) rotate(0deg) scale(1);
      }
      60% {
        transform: translateX(-20%) rotate(-15deg) scale(0.6);
      }
      75% {
        transform: translateX(90%) rotate(-5deg) scale(0.9);
      }
      100% {
        transform: translateX(80%) rotate(-10deg) scale(0.8);
      }
    }
    ```

    ```html [.html]
    <BlossomCarousel class="carousel">
      <div class="slide">
        <div class="card"></div>
      </div>
      <div class="slide">
        <div class="card"></div>
      </div>
      <div class="slide">
        <div class="card"></div>
      </div>
      ...
    </BlossomCarousel>
    ```

    ```ts [.ts]
    carousel.addEventListener("overscroll", (event: CustomEvent) => {
      const overscroll = event.detail.left * 0.2;
      Array.from(event.target.children).forEach((child) => {
        child.style.transform = `translateX(${overscroll}px) rotate(${(overscroll / event.target.clientWidth) * 70}deg) scale(${1 - Math.abs(overscroll) / event.target.clientWidth})`;
      });
    });
    ```
    ::::
  :::

  :::tabs-item{label="Tailwind"}
    ::::code-group
    ```css [.css]
    .carousel {
      --card-width: 12rem;
    }

    .slide {
      transform-origin: center 70%;
      will-change: transform;

      view-timeline: --cards inline;
      animation: stack-cards linear both;
      animation-timeline: --cards;
      animation-range: contain;

      & .card {
        animation: rotate-cards linear both;
        animation-timeline: --cards;
        animation-range: contain -50% contain 150%;
      }
    }

    @keyframes stack-cards {
      0% {
        z-index: calc(100 - sibling-index());
      }
      40% {
        z-index: 1000;
      }
      100% {
        z-index: sibling-index();
      }
    }

    @keyframes rotate-cards {
      0% {
        transform: translateX(-80%) rotate(10deg) scale(0.8);
      }
      25% {
        transform: translateX(-90%) rotate(5deg) scale(0.9);
      }
      50% {
        transform: translateX(0%) rotate(0deg) scale(1);
      }
      60% {
        transform: translateX(-20%) rotate(-15deg) scale(0.6);
      }
      75% {
        transform: translateX(90%) rotate(-5deg) scale(0.9);
      }
      100% {
        transform: translateX(80%) rotate(-10deg) scale(0.8);
      }
    }
    ```

    ```html [.html]
    <BlossomCarousel
      class="carousel grid! snap-x snap-mandatory auto-cols-[100%] grid-flow-col w-[calc(var(--card-width)*3)]! px-(--card-width)"
    >
      <div
        v-for="i in 10"
        :key="i"
        class="slide sticky -left-(--card-width) -right-(--card-width) w-(--card-width) aspect-[3/4] snap-center snap-always"
      >
        <div class="card size-full">{{ i }}</div>
      </div>
    </BlossomCarousel>
    ```

    ```ts [.ts]
    carousel.addEventListener("overscroll", (event: CustomEvent) => {
      const overscroll = event.detail.left * 0.2;
      Array.from(event.target.children).forEach((child) => {
        child.style.transform = `translateX(${overscroll}px) rotate(${(overscroll / event.target.clientWidth) * 70}deg) scale(${1 - Math.abs(overscroll) / event.target.clientWidth})`;
      });
    });
    ```
    ::::
  :::
::


# Flipbook

::supports-view-timeline-support
  :::caution
  View-timeline is not yet supported in this browser. Check browser compatibility at 

  [caniuse.com](https://caniuse.com/?search=scroll-snap-change){rel=""nofollow""}
  :::
::

::supports-view-timeline-safari-support
  :::caution
  Safari's 

  `view-timeline`

   implementation does not yet account for sticky offsets when calculating 

  `animation-range: contain`

  , so scroll-driven animations in this example appear incorrect. See 

  [WebKit bug 288913](https://bugs.webkit.org/show_bug.cgi?id=288913){rel=""nofollow""}

  .
  :::
::

:example-flipbook

::tabs{sync="example-code-style"}
  :::tabs-item{label="CSS"}
    ::::code-group
    ```css [.css]
    .carousel {
      --card-width: 12rem;
      display: grid;
      grid-auto-flow: column;
      grid-auto-columns: 100%;
      scroll-snap-type: x mandatory;
      width: calc(var(--card-width) * 3);
      padding-inline: var(--card-width);
      perspective: 1200px;
    }

    .slide {
      width: var(--card-width);
      aspect-ratio: 3 / 4;
      position: sticky;
      left: calc(var(--card-width) * -1);
      right: calc(var(--card-width) * -1);

      scroll-snap-align: center;
      scroll-snap-stop: always;

      perspective: 1200px;

      view-timeline: --cards inline;
      animation: stack-cards linear both;
      animation-timeline: --cards;
      animation-range: contain;

      & .card {
        width: 100%;
        height: 100%;
        transform-style: preserve-3d;

        animation: rotate-cards linear both;
        animation-timeline: --cards;
        animation-range: contain -50% contain 150%;
      }
    }

    @keyframes stack-cards {
      0% {
        z-index: calc(100 - sibling-index());
      }
      50% {
        z-index: 1000;
      }
      100% {
        z-index: sibling-index();
      }
    }

    @keyframes rotate-cards {
      0% {
        transform: translateX(-100%) translateZ(-200px) rotateY(-35deg);
      }
      25% {
        transform: translateX(-80%) translateZ(-100px) rotateY(-35deg);
      }
      37.5% {
        transform: translateX(-15%) translateZ(-100px) rotateY(-20deg);
      }
      50% {
        transform: translateX(0%) translateZ(0px) rotateY(0deg);
      }
      62.5% {
        transform: translateX(15%) translateZ(-100px) rotateY(20deg);
      }
      75% {
        transform: translateX(80%) translateZ(-100px) rotateY(35deg);
      }
      100% {
        transform: translateX(100%) translateZ(-200px) rotateY(35deg);
      }
    }
    ```

    ```html [.html]
    <BlossomCarousel class="carousel">
      <div class="slide">
        <div class="card"></div>
      </div>
      <div class="slide">
        <div class="card"></div>
      </div>
      <div class="slide">
        <div class="card"></div>
      </div>
      ...
    </BlossomCarousel>
    ```

    ```ts [.ts]
    carousel.addEventListener("overscroll", (event: CustomEvent) => {
      const overscroll = event.detail.left;
      Array.from(event.target.children).forEach((child) => {
        child.style.transform = `translateX(${overscroll * 0.5}px) rotateY(${(overscroll / event.target.clientWidth) * -90}deg)`;
      });
    }
    ```
    ::::
  :::

  :::tabs-item{label="Tailwind"}
    ::::code-group
    ```css [.css]
    .carousel {
      --card-width: 12rem;
    }

    .slide {
      view-timeline: --cards inline;
      animation: stack-cards linear both;
      animation-timeline: --cards;
      animation-range: contain;

      & .card {
        animation: rotate-cards linear both;
        animation-timeline: --cards;
        animation-range: contain -50% contain 150%;
      }
    }

    @keyframes stack-cards {
      0% {
        z-index: calc(100 - sibling-index());
      }
      50% {
        z-index: 1000;
      }
      100% {
        z-index: sibling-index();
      }
    }

    @keyframes rotate-cards {
      0% {
        transform: translateX(-100%) translateZ(-200px) rotateY(-35deg);
      }
      25% {
        transform: translateX(-80%) translateZ(-100px) rotateY(-35deg);
      }
      37.5% {
        transform: translateX(-15%) translateZ(-100px) rotateY(-20deg);
      }
      50% {
        transform: translateX(0%) translateZ(0px) rotateY(0deg);
      }
      62.5% {
        transform: translateX(15%) translateZ(-100px) rotateY(20deg);
      }
      75% {
        transform: translateX(80%) translateZ(-100px) rotateY(35deg);
      }
      100% {
        transform: translateX(100%) translateZ(-200px) rotateY(35deg);
      }
    }
    ```

    ```html [.html]
    <BlossomCarousel
      class="carousel perspective-normal grid! snap-x snap-mandatory auto-cols-[100%] grid-flow-col w-[calc(var(--card-width)*3)]! px-(--card-width)"
    >
      <div
        v-for="i in 10"
        :key="i"
        class="slide perspective-normal sticky -left-(--card-width) -right-(--card-width) w-(--card-width) aspect-[3/4] snap-center snap-always"
      >
        <div class="card transform-3d size-full">{{ i }}</div>
      </div>
    </BlossomCarousel>
    ```

    ```ts [.ts]
    carousel.addEventListener("overscroll", (event: CustomEvent) => {
      const overscroll = event.detail.left;
      Array.from(event.target.children).forEach((child) => {
        child.style.transform = `translateX(${overscroll * 0.5}px) rotateY(${(overscroll / event.target.clientWidth) * -90}deg)`;
      });
    }
    ```
    ::::
  :::
::


# Custom Scrollbar

:example-custom-scrollbar

::tabs{sync="example-code-style"}
  :::tabs-item{label="CSS"}
    ::::code-group
    ```html [.html]
    <div class="example">
      <BlossomCarousel class="carousel">
        <div class="slide"></div>
        <div class="slide"></div>
        <div class="slide"></div>
        ...
      </BlossomCarousel>

      <div class="scrollbar">
        <svg class="track" viewBox="0 0 300 16" fill="none">
          <!-- The faded path is the full track. -->
          <path
            d="cosinePath"
            stroke="currentColor"
            opacity="0.2"
            stroke-width="4"
            stroke-linecap="round"
          />
          <path
            class="progress"
            d="cosinePath"
            stroke="currentColor"
            stroke-width="4"
            stroke-linecap="round"
            pathLength="1"
          />
        </svg>

        <button class="handle"></button>
      </div>
    </div>
    ```

    ```css [.css]
    .example {
      /* Gives the carousel and scrollbar a shared named scroll timeline. */
      timeline-scope: --custom-scrollbar;
    }

    .carousel {
      /* The carousel's horizontal scroll position drives the animations below. */
      scroll-timeline: --custom-scrollbar inline;
    }

    .scrollbar {
      position: relative;
      width: 300px;
      height: 16px;
    }

    .track .progress {
      /* pathLength="1" lets us animate the whole path with values from 1 to 0. */
      animation: progress 1s linear both;
      animation-timeline: --custom-scrollbar;
      stroke-dasharray: 1;
    }

    .handle {
      position: absolute;
      top: 0;
      left: 0;
      
      /* Same path data as the SVG stroke, in CSS pixels.
         url(#id) follows the SVG geometry, which Chrome 155+ resolves in
         device pixels, so on a 2× display the handle travels half as far. */
      offset-path: path("cosinePath");
      offset-anchor: auto;

      animation: handle 1s linear both;
      animation-timeline: --custom-scrollbar;
    }

    @keyframes progress {
      from {
        stroke-dashoffset: 1;
      }
      to {
        stroke-dashoffset: 0;
      }
    }

    @keyframes handle {
      from {
        offset-distance: 0%;
      }
      to {
        offset-distance: 100%;
      }
    }
    ```

    ```ts [.ts]
    let svgRect: DOMRect
    let offsetX: number
    let activeHandle: HTMLButtonElement | null = null

    const carousel = document.querySelector<HTMLElement>('.carousel')!
    const svg = document.querySelector<SVGSVGElement>('.track')!
    const handle = document.querySelector<HTMLButtonElement>('.handle')!

    handle.addEventListener('pointerdown', onPointerDown)

    function onPointerDown(event: PointerEvent) {
      const handleRect = handle.getBoundingClientRect()

      // Keep receiving pointer events while dragging outside the handle.
      activeHandle = handle
      handle.setPointerCapture(event.pointerId)

      // Measure once at the start so pointer movement maps to track progress.
      svgRect = svg.getBoundingClientRect()
      offsetX = event.clientX - handleRect.left

      window.addEventListener('pointermove', onPointerMove)
      window.addEventListener('pointerup', onPointerUp)
    }

    function onPointerMove(event: PointerEvent) {
      const newX = event.clientX - offsetX
      const percentageX = ((newX - svgRect.left) / svgRect.width) * 100

      // Convert track progress to the carousel's scroll range.
      carousel.scrollTo({
        left: (percentageX / 100) * (carousel.scrollWidth - carousel.clientWidth),
        behavior: 'instant',
      })
    }

    function onPointerUp(event: PointerEvent) {
      activeHandle?.releasePointerCapture(event.pointerId)
      activeHandle = null

      window.removeEventListener('pointermove', onPointerMove)
      window.removeEventListener('pointerup', onPointerUp)
    }
    ```
    ::::
  :::

  :::tabs-item{label="Tailwind"}
    ::::code-group
    ```html [.html]
    <div class="group relative flex w-full flex-col items-center gap-6">
      <BlossomCarousel class="carousel grid! auto-cols-[200px] grid-flow-col gap-4">
        <div class="aspect-3/4 w-full"></div>
        <div class="aspect-3/4 w-full"></div>
        <div class="aspect-3/4 w-full"></div>
        ...
      </BlossomCarousel>

      <div class="relative h-4 w-[300px]">
        <svg class="track h-full w-full" viewBox="0 0 300 16" fill="none">
          <!-- The faded path is the full track. -->
          <path
            d="cosinePath"
            stroke="currentColor"
            opacity="0.2"
            stroke-width="4"
            stroke-linecap="round"
          />
          <path
            d="cosinePath"
            stroke="currentColor"
            stroke-width="4"
            stroke-linecap="round"
            pathLength="1"
          />
        </svg>

        <button class="handle absolute top-0 left-0 size-3 rounded-full"></button>
      </div>
    </div>
    ```

    ```css [.css]
    .group {
      /* Gives the carousel and scrollbar a shared named scroll timeline. */
      timeline-scope: --custom-scrollbar;
    }

    .carousel {
      /* The carousel's horizontal scroll position drives the animations below. */
      scroll-timeline: --custom-scrollbar inline;
    }

    svg path:last-child {
      /* pathLength="1" lets us animate the whole path with values from 1 to 0. */
      animation: progress 1s linear both;
      animation-timeline: --custom-scrollbar;
      stroke-dasharray: 1;
    }

    .handle {
      /* Same path data as the SVG stroke, in CSS pixels.
         url(#id) follows the SVG geometry, which Chrome 155+ resolves in
         device pixels, so on a 2× display the handle travels half as far. */
      offset-path: path("cosinePath");
      offset-anchor: auto;
      animation: handle 1s linear both;
      animation-timeline: --custom-scrollbar;
    }

    @keyframes progress {
      from {
        stroke-dashoffset: 1;
      }
      to {
        stroke-dashoffset: 0;
      }
    }

    @keyframes handle {
      from {
        offset-distance: 0%;
      }
      to {
        offset-distance: 99%;
      }
    }
    ```

    ```ts [.ts]
    let svgRect: DOMRect
    let offsetX: number
    let activeHandle: HTMLButtonElement | null = null

    const carousel = document.querySelector<HTMLElement>('.carousel')!
    const svg = document.querySelector<SVGSVGElement>('.track')!
    const handle = document.querySelector<HTMLButtonElement>('.handle')!

    handle.addEventListener('pointerdown', onPointerDown)

    function onPointerDown(event: PointerEvent) {
      const handleRect = handle.getBoundingClientRect()

      // Keep receiving pointer events while dragging outside the handle.
      activeHandle = handle
      handle.setPointerCapture(event.pointerId)

      // Measure once at the start so pointer movement maps to track progress.
      svgRect = svg.getBoundingClientRect()
      offsetX = event.clientX - handleRect.left

      window.addEventListener('pointermove', onPointerMove)
      window.addEventListener('pointerup', onPointerUp)
    }

    function onPointerMove(event: PointerEvent) {
      const newX = event.clientX - offsetX
      const percentageX = ((newX - svgRect.left) / svgRect.width) * 100

      // Convert track progress to the carousel's scroll range.
      carousel.scrollTo({
        left: (percentageX / 100) * (carousel.scrollWidth - carousel.clientWidth),
        behavior: 'instant',
      })
    }

    function onPointerUp(event: PointerEvent) {
      activeHandle?.releasePointerCapture(event.pointerId)
      activeHandle = null

      window.removeEventListener('pointermove', onPointerMove)
      window.removeEventListener('pointerup', onPointerUp)
    }
    ```
    ::::
  :::
::


# Timeline

:example-timeline

::tabs{sync="example-code-style"}
  :::tabs-item{label="CSS"}
    ::::code-group
    ```css [.css]
    .tracks {
      display: grid;
      width: max-content;
      gap: 0.125rem;
    }

    .track {
      display: flex;
      height: 3rem;
      gap: 0.125rem;
      padding-inline: 3rem;
    }

    .clip {
      padding: 0.25rem 0.5rem;
      border-radius: 0.5rem;
    }

    .clip-label {
      position: sticky;
      left: 0.5rem;
      right: 0.5rem;
      width: fit-content;
    }
    ```

    ```html [.html]
    <BlossomCarousel>
      <div class="tracks">
        <div class="track">
          <div class="clip" style="width: 180px">
            <p class="clip-label">A quiet bloom begins</p>
          </div>
          <div class="clip" style="width: 530px; margin-left: 92px">
            <p class="clip-label">Soft Blossom Preset</p>
          </div>
          ...
        </div>
        <div class="track">
          ...
        </div>
        ...
      </div>
    </BlossomCarousel>
    ```
    ::::
  :::

  :::tabs-item{label="Tailwind"}
  ```html [.html]
  <BlossomCarousel>
    <div class="grid! w-max gap-0.5">
      <div class="flex h-12 gap-0.5 px-12">
        <div class="flex! px-2 py-1 h-full bg-primary/40 rounded-lg" style="width: 180px">
          <p class="sticky left-2 right-2 truncate">A quiet bloom begins</p>
        </div>
        <div class="flex! px-2 py-1 h-full bg-primary/40 rounded-lg" style="width: 530px; margin-left: 92px">
          <p class="sticky left-2 right-2 truncate">Soft Blossom Preset</p>
        </div>
        ...
      </div>
      <div class="flex h-12 gap-0.5 px-12">
        ...
      </div>
      ...
    </div>
  </BlossomCarousel>
  ```
  :::
::


# CSS Controls

::supports-scroll-marker-support
  :::caution
  css ::scroll-marker is not yet supported in this browser. Check browser compatibility at 

  [caniuse.com](https://caniuse.com/#feat=css-container-queries){rel=""nofollow""}
  :::
::

:example-css-controls

::tabs{sync="example-code-style"}
  :::tabs-item{label="CSS"}
    ::::code-group
    ```css [.css]
    .container {
      anchor-name: --carousel;
    }

    .carousel {
      display: grid;
      grid-auto-flow: column;
      grid-auto-columns: 200px;
      gap: 1rem;
      scroll-marker-group: after;

      &::scroll-button(*) {
        position: fixed;
        position-anchor: --carousel;
        position-visibility: always;

        border: none;
        font-size: 1rem;
        background: white;
        color: cyan;
        aspect-ratio: 1;
        border-radius: 50%;
        cursor: pointer;
        box-shadow: 0 1px 8px 0 rgb(0 0 0 / 0.2);
        transition: 100ms scale ease;
        z-index: 1;
      }

      &::scroll-button(*):hover {
        scale: 1.1;
      }

      &::scroll-button(*):active {
        scale: 0.98;
      }

      &::scroll-button(left) {
        position-area: inline-start center;
        left: calc(anchor(left) + 2.5rem);
        padding-right: 0.55rem;
        content: "◄" / "Previous";
      }

      &::scroll-button(right) {
        position-area: inline-end center;
        left: calc(anchor(right) - 2.5rem);
        padding-left: 0.55rem;
        content: "►" / "Next";
      }

      &::scroll-marker-group {
        position: fixed;
        position-anchor: --carousel;
        position-area: block-end;
        top: calc(anchor(bottom) - 3rem);
        position-visibility: always;
        margin: 10px;

        display: grid;
        grid-auto-columns: 1rem;
        grid-auto-flow: column;
        gap: 0.5rem;
      }

      > .slide {
        width: 100%;
        aspect-ratio: 3 / 4;

        &::scroll-marker {
          content: "";
          aspect-ratio: 1;
          border-radius: 50%;
          background: cyan;
          opacity: 0.3;
        }

        &::scroll-marker:hover {
          opacity: 0.8;
        }

        &::scroll-marker:target-current {
          opacity: 1;
        }
      }
    }
    ```

    ```html [.html]
    <div class="container">
      <BlossomCarousel class="carousel">
        <div class="slide"></div>
        <div class="slide"></div>
        <div class="slide"></div>
        ...
      </BlossomCarousel>
    </div>
    ```
    ::::
  :::

  :::tabs-item{label="Tailwind"}
  ```html [.html]
  <div class="container">
    <BlossomCarousel class="carousel">
      <div class="slide"></div>
      <div class="slide"></div>
      <div class="slide"></div>
      ...
    </BlossomCarousel>
  </div>
  ```
  :::
::

::note{color="neutral" icon="i-lucide-lightbulb"}
Learn more about 

[CSS Carousels](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Overflow/Carousels){rel=""nofollow""}

.
::


# Scroll State Query

::supports-scroll-state-support
  :::caution
  Scroll-state queries are not yet supported in this browser. Check browser compatibility at 

  [caniuse.com](https://caniuse.com/#feat=css-container-queries){rel=""nofollow""}
  :::
::

:example-scroll-state

::tabs{sync="example-code-style"}
  :::tabs-item{label="CSS"}
    ::::code-group
    ```css [.css]
    .carousel {
      display: grid;
      grid-auto-flow: column;
      grid-auto-columns: 200px;
      gap: 1rem;
      scroll-snap-type: x mandatory;
    }

    .slide {
      width: 100%;
      aspect-ratio: 3 / 4;
      scroll-snap-align: center;

      container-type: scroll-state;
      container-name: snap-container;
    }

    .card {
      width: 100%;
      height: 100%;
      background: color-mix(in srgb, var(--color-primary) 50%, transparent);
    }

    @container snap-container scroll-state(snapped: x) {
      .card {
        background: var(--color-primary);
      }
    }
    ```

    ```html [.html]
    <BlossomCarousel class="carousel">
      <div class="slide">
        <div class="card"></div>
      </div>
      <div class="slide">
        <div class="card"></div>
      </div>
      <div class="slide">
        <div class="card"></div>
      </div>
      ...
    </BlossomCarousel>
    ```
    ::::
  :::

  :::tabs-item{label="Tailwind"}
    ::::code-group
    ```css [.css]
    .slide {
      container-type: scroll-state;
      container-name: snap-container;
    }

    @container snap-container scroll-state(snapped: x) {
      .card {
        background: var(--color-primary);
      }
    }
    ```

    ```html [.html]
    <BlossomCarousel
      class="grid! auto-cols-[200px] snap-x snap-mandatory grid-flow-col gap-4"
    >
      <div class="slide w-full snap-center aspect-3/4">
        <div class="card size-full bg-primary/50"></div>
      </div>
      <div class="slide w-full snap-center aspect-3/4">
        <div class="card size-full bg-primary/50"></div>
      </div>
      <div class="slide w-full snap-center aspect-3/4">
        <div class="card size-full bg-primary/50"></div>
      </div>
      ...
    </BlossomCarousel>
    ```
    ::::
  :::
::


# Scroll Snap Events

::supports-scroll-snap-event-support
  :::caution
  Scroll-snap events are not yet supported in this browser. Check browser compatibility at 

  [caniuse.com](https://caniuse.com/?search=scroll-snap-change){rel=""nofollow""}
  :::
::

:example-scroll-snap-events

::code-group
```ts [.ts]
const carousel = document.querySelector(".carousel") as HTMLElement;
const videos = carousel.querySelectorAll("video");

carousel.addEventListener("scrollsnapchange", (event) => {
  (event.snapTargetInline as HTMLVideoElement)?.play();
});

carousel.addEventListener("scrollsnapchanging", () => {
  videos.forEach((video) => video.pause());
});
```

```css [.css]
.carousel {
  display: grid;
  grid-auto-flow: column;
  grid-auto-columns: 400px;
  gap: 1rem;
  scroll-snap-type: x mandatory;
}

.slide {
  width: 100%;
  aspect-ratio: 16 / 9;
  scroll-snap-align: center;
  object-fit: cover;
  border-radius: 0.5rem;
}
```

```html [.html]
<BlossomCarousel class="carousel">
  <video
    class="slide"
    src="cat.mp4"
    playsinline
    loop
    muted
    preload="metadata"
  ></video>
  <video
    class="slide"
    src="corgi.mp4"
    playsinline
    loop
    muted
    preload="metadata"
  ></video>
  <video
    class="slide"
    src="bunny.mp4"
    playsinline
    loop
    muted
    preload="metadata"
  ></video>
  ...
</BlossomCarousel>
```
::


# Repeat

::warning
This feature is experimental and might not work as expected.
::

:example-repeat

```html [.html]
<BlossomCarousel repeat="true" class="carousel">
  <div class="slide"></div>
  <div class="slide"></div>
  <div class="slide"></div>
  ...
</BlossomCarousel>
```


# Scroll Trigger

::supports-scroll-trigger-support
  :::caution
  Animation-trigger is not yet supported in this browser. Check browser compatibility at 

  [caniuse.com](https://caniuse.com/?search=animation-trigger){rel=""nofollow""}
  :::
::

:example-scroll-trigger

::tabs{sync="example-code-style"}
  :::tabs-item{label="CSS"}
    ::::code-group
    ```css [.css]
    .carousel {
      display: grid;
      grid-auto-flow: column;
      grid-auto-columns: 200px;
      gap: 1rem;
      scroll-snap-type: x mandatory;
    }

    .slide {
      width: 100%;
      aspect-ratio: 3 / 4;
      scroll-snap-align: center;

      timeline-trigger-name: --t;
      timeline-trigger-source: view(inline);
      animation: unclip 0.35s ease-in-out both;
      animation-trigger: --t play-forwards play-backwards;
    }

    @keyframes unclip {
      from {
        clip-path: inset(100% 0 0 0 round 1rem);
      }
      to {
        clip-path: inset(0);
      }
    }
    ```

    ```html [.html]
    <BlossomCarousel class="carousel">
      <div class="slide"></div>
      <div class="slide"></div>
      <div class="slide"></div>
      ...
    </BlossomCarousel>
    ```
    ::::
  :::

  :::tabs-item{label="Tailwind"}
    ::::code-group
    ```css [.css]
    .slide {
      timeline-trigger-name: --t;
      timeline-trigger-source: view(inline);
      animation: unclip 0.35s ease-in-out both;
      animation-trigger: --t play-forwards play-backwards;
    }

    @keyframes unclip {
      from {
        clip-path: inset(100% 0 0 0 round 1rem);
      }
      to {
        clip-path: inset(0);
      }
    }
    ```

    ```html [.html]
    <BlossomCarousel
      class="grid! auto-cols-[200px] snap-x snap-mandatory grid-flow-col gap-4"
    >
      <div class="slide w-full snap-center aspect-3/4"></div>
      <div class="slide w-full snap-center aspect-3/4"></div>
      <div class="slide w-full snap-center aspect-3/4"></div>
      ...
    </BlossomCarousel>
    ```
    ::::
  :::
::


# Examples

:examples-table


# Accessibility Guide

Accessible carousels are not created by adding a single ARIA attribute. They depend on ordinary web fundamentals working together: meaningful HTML, reachable controls, predictable focus, controllable motion, visible state, and tested assistive technology output.

Blossom gives you a native scroll container and progressive drag support. The accessibility of the carousel still depends on the markup, controls, labels, and behavior you build around that container.

::note{color="neutral" icon="i-lucide-info"}
WCAG is a baseline, not a guarantee of usability. A carousel can pass automated checks and still be confusing if controls are unnamed, focus moves into hidden content, or screen readers hear semantics that do not match the visual pattern.
::

## Start with the right pattern

Not every horizontal scroller needs to be announced as a carousel. Choose the lightest pattern that matches the content and behavior.

| Pattern                 | Use when                                                                          | Recommended structure                                                             |
| ----------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Scrollable list         | Several related items are visible and users can scroll through them naturally.    | A list such as `<ul>` with `<li>` items, plus optional previous and next buttons. |
| Carousel region         | The component is a distinct page feature with slides and controls.                | A labelled `<section>` or `role="region"` with `aria-roledescription="carousel"`. |
| Tabbed carousel         | Only one slide is displayed at a time and slide pickers behave exactly like tabs. | A real tabs pattern with `tablist`, `tab`, and `tabpanel`.                        |
| Gallery or product rail | Multiple cards are visible at once and all cards remain normal page content.      | A list of articles/cards with ordinary links and buttons.                         |

Avoid giving a component a role that promises behavior you do not implement. If the user hears "tab", arrow keys, selected state, and tabpanel relationships need to work like a tabs widget.

## Use semantic slide markup

When slides are a set of related items, use a list. This gives assistive technologies a familiar count and structure.

```html [List-based carousel]
<section aria-labelledby="featured-heading">
  <h2 id="featured-heading">Featured articles</h2>

  <div class="carousel-controls">
    <BlossomPrev for="featured" aria-label="Previous articles" />
    <BlossomNext for="featured" aria-label="Next articles" />
  </div>

  <BlossomCarousel id="featured" as="ul" class="carousel">
    <li data-blossom-slide>
      <article>
        <h3>Designing with native scrolling</h3>
        <a href="/articles/native-scrolling">Read article</a>
      </article>
    </li>
    <li data-blossom-slide>
      <article>
        <h3>Understanding scroll snap</h3>
        <a href="/articles/scroll-snap">Read article</a>
      </article>
    </li>
  </BlossomCarousel>
</section>
```

Use a carousel role description only when the component benefits from being identified as a carousel.

```html [Named carousel region]
<section
  aria-labelledby="product-carousel-heading"
  aria-roledescription="carousel"
>
  <h2 id="product-carousel-heading">Popular products</h2>
  <!-- controls and slides -->
</section>
```

The accessible label should not repeat the word "carousel" when `aria-roledescription="carousel"` is present. A screen reader may announce the role description after the label, so "Popular products carousel, carousel" is noisy.

## Provide real controls

Dragging and swiping are not enough. WCAG 2.5.7 requires functionality that uses dragging to have a non-drag alternative unless dragging is essential.

Use real buttons for carousel actions:

- Previous slide or previous set.
- Next slide or next set.
- Pause and play, if the carousel auto-rotates.
- Slide picker controls, if users can jump to a specific slide.

### Built-in navigation components

Blossom ships navigation components that cover these requirements out of the box. `<BlossomPrev>`, `<BlossomNext>`, and `<BlossomDots>` render native buttons, connect to the carousel through its `id`, and provide a keyboard-operable, non-drag alternative — even on touch devices where the drag engine is not loaded.

```html [Built-in controls]
<BlossomCarousel id="products" class="carousel">
  <div data-blossom-slide class="slide"><!-- slide content --></div>
  <div data-blossom-slide class="slide"><!-- slide content --></div>
  <div data-blossom-slide class="slide"><!-- slide content --></div>
</BlossomCarousel>

<BlossomPrev for="products" />
<BlossomDots for="products" />
<BlossomNext for="products" />
```

Mark each slide with `data-blossom-slide` so the controls can track the slide count, the active slide, and the first and last positions.

What the components expose to assistive technologies:

- Every control is a native `<button type="button">`, so `Enter` and `Space` activation, focus behavior, and speech control work without extra scripting.
- `<BlossomPrev>` and `<BlossomNext>` have the default accessible names "Previous slide" and "Next slide", and reference the carousel with `aria-controls`.
- `<BlossomPrev>` and `<BlossomNext>` disable automatically at the first and last slide using the native `disabled` attribute, so unavailable controls leave the tab order.
- `<BlossomDots>` renders a `role="group"` labelled "Choose slide to display". Each dot is named "Go to slide 1", "Go to slide 2", and so on, and the current dot exposes `aria-current`.
- Activation scrolls the carousel without moving focus, so users can press the same button repeatedly.

The default names are generic on purpose. When your carousel shows products or articles, pass a more specific label:

```html [More specific control names]
<BlossomPrev for="products" aria-label="Previous products" />
<BlossomNext for="products" aria-label="Next products" />
```

### Custom controls

If you build your own controls instead, apply the same rules by hand:

```html [Carousel buttons]
<button type="button" aria-label="Previous product">Previous</button>
<button type="button" aria-label="Next product">Next</button>
```

If multiple items are visible at once, name controls for what they actually do. "Next products" or "Next articles" can be more honest than "Next slide".

Do not disable previous and next buttons only visually. If a button cannot perform an action, use the native `disabled` attribute when it should be skipped in the tab order.

```html [Disabled edge control]
<button type="button" aria-label="Previous product" disabled>Previous</button>
```

For slide picker buttons, `aria-disabled="true"` can be useful for the current slide picker when users benefit from encountering the current item in the tab sequence.

```html [Current slide picker]
<div role="group" aria-label="Choose product">
  <button type="button" aria-disabled="true">Canvas tote</button>
  <button type="button">Wool scarf</button>
  <button type="button">Ceramic mug</button>
</div>
```

## Name every control clearly

Every carousel control needs a unique accessible name. Repeated names like "Show slide" or "Read more" make the carousel hard to operate with screen readers and speech control.

Good names tell the user what will happen:

```html [Specific control names]
<button type="button" aria-label="Show canvas tote">1</button>
<button type="button" aria-label="Show wool scarf">2</button>
<button type="button" aria-label="Show ceramic mug">3</button>
```

If slide names are not available, use position and set size.

```html [Position-based names]
<button type="button" aria-label="Show slide 1 of 5">1</button>
<button type="button" aria-label="Show slide 2 of 5">2</button>
```

This is what the built-in components do: `<BlossomPrev>` and `<BlossomNext>` default to "Previous slide" and "Next slide", and `<BlossomDots>` names each dot "Go to slide 1", "Go to slide 2", and so on. Override the prev and next labels with `aria-label` when more specific names fit the content better.

When visible text exists, keep the accessible name aligned with it. This helps speech recognition users activate controls by the words they can see.

```html [Label in name]
<button type="button" aria-label="Next products">Next</button>
```

Icon-only buttons need a name on the button. Hide the icon itself if it is decorative.

```html [Icon-only carousel button]
<button type="button" aria-label="Next product">
  <svg aria-hidden="true" focusable="false"><!-- icon --></svg>
</button>
```

## Keep keyboard behavior predictable

Keyboard users should be able to reach the carousel, understand the controls, operate them repeatedly, and leave the component without surprise.

Expected behavior:

- `Tab` and `Shift + Tab` move through controls and focusable slide content in DOM order.
- `Enter` and `Space` activate carousel buttons.
- Previous and next buttons do not move focus after activation.
- Focus is always visible.
- Focus does not land on content that is visually hidden or intentionally unavailable.
- Keyboard users can access the same functionality as pointer and touch users.

You usually do not need custom scripting for `Tab`. Let the browser handle normal tab order unless you are implementing a real composite widget such as tabs.

```css [Visible focus]
.carousel :focus-visible,
.carousel-controls :focus-visible {
  outline: 3px solid currentColor;
  outline-offset: 3px;
}
```

Avoid positive `tabindex` values. Put controls and slides in the DOM order users should experience.

## Do not trap focus in off-screen slides

Native horizontal scrolling often keeps all slides in the document flow. That is good for simple scrollable lists, but it can be confusing when a carousel presents itself as showing only one slide.

If all slides remain part of the normal content, it is acceptable for keyboard focus to move through them in order. In that case, do not claim the component behaves like tabs or like a single active panel.

If only one slide should be available at a time, inactive slides need to be unavailable to both keyboard and assistive technology users. Depending on the implementation, use conditional rendering, `hidden`, `inert`, or another approach that removes inactive interactive content from the tab order and accessibility tree.

```html [Inactive slide removed]
<div role="group" aria-roledescription="slide" aria-label="1 of 3">
  <h3>Canvas tote</h3>
  <a href="/products/canvas-tote">View product</a>
</div>

<div hidden>
  <h3>Wool scarf</h3>
  <a href="/products/wool-scarf">View product</a>
</div>
```

Do not use `aria-hidden="true"` on a slide that still contains focusable links or buttons. That creates focusable controls that are hidden from assistive technologies.

## Handle motion and auto-rotation

Auto-rotation is one of the easiest ways to make a carousel inaccessible. It can move content before users finish reading, disorient screen reader users, and distract people with attention or vestibular disabilities.

If a carousel auto-rotates:

- Provide a pause or stop button.
- Put the rotation control before the rotating content in the tab order.
- Stop rotation when keyboard focus enters the carousel.
- Stop rotation when the pointer hovers over the carousel.
- Do not restart rotation unless the user explicitly asks for it.
- Keep the control label action-based, such as "Pause featured articles" and "Play featured articles".

```html [Rotation control]
<button type="button" aria-label="Pause featured articles">Pause</button>
```

Respect reduced motion preferences for scripted animation, transitions, and smooth scrolling.

```css [Reduced motion]
@media (prefers-reduced-motion: reduce) {
  .carousel {
    scroll-behavior: auto;
  }

  .carousel *,
  .carousel *::before,
  .carousel *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}
```

## Announce changes with care

Not every carousel movement needs a live region. Over-announcing slide changes can be as disruptive as not announcing them.

Use these defaults:

- Use `aria-live="off"` while a carousel is auto-rotating.
- Use `aria-live="polite"` for user-initiated slide changes when the changed content is not otherwise obvious to assistive technologies.
- Do not move focus just to announce a slide change.
- Keep announcements short, such as "Slide 2 of 5" or the slide title.

```html [Slide status]
<p class="visually-hidden" aria-live="polite" aria-atomic="true">
  Showing wool scarf, slide 2 of 5
</p>
```

If focus moves to the newly shown slide content as part of a deliberate workflow, an additional live region may be redundant.

## Choose picker semantics carefully

Slide pickers can be buttons or tabs. The choice matters.

Use buttons when:

- Multiple slides can be visible at once.
- Slides are part of a scrollable list.
- Picker controls jump the scroll position but do not hide every other slide.
- You want simple `Tab` navigation through each picker.

`<BlossomDots>` follows the button pattern: a labelled `role="group"` of native buttons where the active dot exposes `aria-current`. This matches Blossom's behavior, since dots move the scroll position without hiding other slides. Do not wrap `<BlossomDots>` in tab semantics.

Use tabs only when:

- One panel is presented at a time.
- Each `tab` has a corresponding `tabpanel`.
- The selected tab state is always correct.
- Inactive tabpanels are hidden from users.
- Arrow key behavior follows the tabs pattern.

```html [Tabbed carousel shape]
<div aria-label="Featured products" aria-roledescription="carousel">
  <div role="tablist" aria-label="Choose product">
    <button
      role="tab"
      aria-selected="true"
      aria-controls="panel-tote"
      id="tab-tote"
    >
      Canvas tote
    </button>
    <button
      role="tab"
      aria-selected="false"
      aria-controls="panel-scarf"
      id="tab-scarf"
    >
      Wool scarf
    </button>
  </div>

  <div role="tabpanel" id="panel-tote" aria-labelledby="tab-tote">
    <h3>Canvas tote</h3>
  </div>

  <div role="tabpanel" id="panel-scarf" aria-labelledby="tab-scarf" hidden>
    <h3>Wool scarf</h3>
  </div>
</div>
```

A scroller that merely moves content left and right is usually not a tabs widget.

## Keep visual states perceivable

Carousel state should not depend on color alone.

- Give active slide pickers a visible shape, outline, underline, icon, or text change in addition to color.
- Ensure focus indicators have at least 3:1 contrast against adjacent colors.
- Ensure icon buttons and disabled states remain understandable in forced colors mode.
- Do not hide scrollbars unless an equally clear affordance and keyboard path remain.
- Make touch targets at least 24 by 24 CSS pixels, and aim for 44 by 44 CSS pixels when space allows.

```css [Forced colors-friendly states]
.carousel-picker[aria-current="true"],
.carousel-picker[aria-disabled="true"] {
  outline: 2px solid currentColor;
}

@media (forced-colors: active) {
  .carousel-picker[aria-current="true"],
  .carousel-picker[aria-disabled="true"] {
    outline-color: Highlight;
  }
}
```

## Test the carousel as a component

Automated checks are useful, but carousel accessibility depends heavily on behavior. Manual testing is essential.

Carousel test checklist:

- The carousel has a clear accessible name when it is exposed as a region or group.
- Previous, next, pause, play, and picker controls are real buttons or fully implement button behavior.
- Every control has a unique accessible name.
- All pointer and drag functionality has a keyboard alternative.
- `Tab` order follows the visual and reading order.
- Focus remains visible and is not hidden by sticky controls or clipped slide containers.
- Previous and next controls can be activated repeatedly without focus moving unexpectedly.
- Disabled or unavailable controls expose the correct disabled state.
- Auto-rotation pauses on focus and hover.
- Auto-rotation does not restart without user action.
- Reduced motion preferences are respected.
- Screen reader output matches the visible component: roles, names, selected states, and announcements are not misleading.
- Off-screen or inactive slides do not create unexpected tab stops for the chosen pattern.
- Slide picker semantics match the behavior: buttons for simple picker controls, tabs only for real tabbed panels.
- The component works at 200 percent zoom and narrow viewport sizes.
- Active, focus, disabled, and selected states remain visible in forced colors mode.

## Carousel WCAG map

The most relevant WCAG success criteria for carousels are usually these:

| Criteria                     | Carousel check                                                                               |
| ---------------------------- | -------------------------------------------------------------------------------------------- |
| 1.1.1 Non-text Content       | Images, icon buttons, and thumbnails have appropriate text alternatives or accessible names. |
| 1.3.1 Info and Relationships | Slide structure, control groups, labels, and selected states are programmatically exposed.   |
| 1.3.2 Meaningful Sequence    | DOM order matches the reading and keyboard order.                                            |
| 1.4.1 Use of Color           | Active, selected, disabled, and error states are not conveyed by color alone.                |
| 1.4.3 Contrast Minimum       | Text inside slides and controls meets contrast requirements.                                 |
| 1.4.10 Reflow                | The carousel works when zoomed or viewed in narrow layouts.                                  |
| 1.4.11 Non-text Contrast     | Buttons, focus indicators, and active picker states have sufficient contrast.                |
| 2.1.1 Keyboard               | All carousel functionality works with a keyboard.                                            |
| 2.1.2 No Keyboard Trap       | Users can leave the carousel with normal keyboard navigation.                                |
| 2.2.2 Pause, Stop, Hide      | Auto-rotating or moving content can be paused, stopped, or hidden.                           |
| 2.4.3 Focus Order            | Focus moves through controls and slide content in a meaningful order.                        |
| 2.4.7 Focus Visible          | Keyboard focus is always visible.                                                            |
| 2.4.11 Focus Not Obscured    | Focused controls and slide links are not hidden by overlays or clipping.                     |
| 2.5.3 Label in Name          | Visible control text is included in the accessible name.                                     |
| 2.5.7 Dragging Movements     | Dragging has a non-drag alternative.                                                         |
| 2.5.8 Target Size Minimum    | Controls and picker targets are large enough to operate.                                     |
| 3.2.1 On Focus               | Focusing a control does not unexpectedly change context.                                     |
| 4.1.2 Name, Role, Value      | Custom controls expose correct names, roles, values, and states.                             |
| 4.1.3 Status Messages        | Slide changes are announced when appropriate without moving focus.                           |

## Useful resources

- [WAI Carousels Tutorial](https://www.w3.org/WAI/tutorials/carousels/){rel="&#x22;nofollow&#x22;"} - accessible carousel structure, functionality, animation, and styling guidance.
- [ARIA Authoring Practices Guide: Carousel Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/carousel/){rel="&#x22;nofollow&#x22;"} - expected carousel roles, states, properties, and keyboard behavior.
- [ARIA Authoring Practices Guide: Tabs Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/){rel="&#x22;nofollow&#x22;"} - use this when slide pickers are truly tabs.
- [WCAG 2.2 Quick Reference](https://www.w3.org/WAI/WCAG22/quickref/){rel="&#x22;nofollow&#x22;"} - success criteria, techniques, and filters.


# Agent Skills

Blossom Carousel's Agent Skills help AI coding assistants give package-specific guidance.

## Install the skills

Compatible agents (Cursor, Claude Code, etc.) can discover and use skills automatically.

To manually install with the skills CLI:

::code-block
```bash [Terminal]
npx skills add https://www.blossom-carousel.com
```

## Available skills

| Skill                     | Use it when                                                                                                        |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `blossom-carousel-core`   | You are working with the framework-agnostic Core package, direct DOM setup, lazy loading, `init()`, or `destroy()` |
| `blossom-carousel-vue`    | You are using Blossom Carousel in Vue or Nuxt                                                                      |
| `blossom-carousel-react`  | You are using Blossom Carousel in React or Next.js                                                                 |
| `blossom-carousel-svelte` | You are using Blossom Carousel in Svelte or SvelteKit                                                              |
| `blossom-carousel-web`    | You are using the Web Component package or CDN setup                                                               |

## How to use a skill

When your AI coding agent supports skills, you can ask for the package or framework directly. The agent can then use the matching skill automatically.

Good prompts name the framework, the desired carousel pattern, and any constraints that matter.

  :::prompt
  ---
  actions:
    - copy
  description: Build an accessible testimonial carousel in React.
  icon: i-lucide-square-chevron-right
  ---
  Use Blossom Carousel React to build an accessible testimonial carousel. Keep layout in CSS and use scroll snap.
  :::

  :::prompt
  ---
  actions:
    - copy
  description: Create a product carousel with semantic list markup in Nuxt.
  icon: i-lucide-square-chevron-right
  ---
  Use Blossom Carousel Vue in Nuxt. Register the component globally and create a product carousel with semantic list markup.
  :::

  :::prompt
  ---
  actions:
    - copy
  description: Create an RTL carousel with Web Components.
  icon: i-lucide-square-chevron-right
  ---
  Use Blossom Carousel Web Components from a CDN. Create an RTL carousel and include the required stylesheet link.
  :::

  :::note{color="neutral" icon="i-lucide-lightbulb"}
  For implementation details, use the matching 

  [framework guide](https://www.blossom-carousel.com/docs/framework-guides/vue-nuxt)

  .
  :::
::

## What the skills help with

The skills keep implementation guidance consistent across packages.

- Use the right package import for the chosen framework.
- Import the stylesheet from your framework package (for example `@blossom-carousel/vue/style.css`).
- Use the framework component instead of the Web Component when working in Vue, React, or Svelte.
- Use the `as` prop for semantic root elements in framework wrappers.
- Use `Blossom(element)`, `init()`, and `destroy()` for direct Core usage.
- Check common setup problems such as missing styles, invalid slide structure, and duplicate Core initialization.


# Embla

Embla creates a carousel engine around a viewport, container, options object, event system, and plugin API.

Blossom keeps the carousel as a native scroll container. Layout, snapping, alignment, spacing, direction, and responsive behavior belong in CSS.

## Migration mindset

When moving from Embla to Blossom, migrate the carousel in three steps:

1. Replace the Embla viewport and container structure with a single `<BlossomCarousel>` root.
2. Move Embla options such as alignment, axis, slide sizing, and containment into CSS.
3. Replace Embla API calls with Blossom methods, native scroll APIs, and browser observers.

::note{color="neutral" icon="i-lucide-lightbulb"}
Most Blossom migrations replace abstract JavaScript configuration with native expressions using CSS scroll snap, grid, sticky positioning, or native scrol API's.
::

## Installation

Remove the Embla package for your framework and install the matching Blossom package.

::code-group{sync="migration-code-style"}
```bash [Vue]
npm uninstall embla-carousel-vue
npm install @blossom-carousel/vue
```

```bash [React]
npm uninstall embla-carousel-react
npm install @blossom-carousel/react
```

```bash [Svelte]
npm uninstall embla-carousel-svelte
npm install @blossom-carousel/svelte
```

```bash [Core]
npm uninstall embla-carousel
npm install @blossom-carousel/core
```
::

Import the stylesheet from your framework package once in your app.

::code-group
```js [Vue]
import "@blossom-carousel/vue/style.css";
```

```js [React]
import "@blossom-carousel/react/style.css";
```

```js [Svelte]
import "@blossom-carousel/svelte/style.css";
```

```js [Core]
import "@blossom-carousel/core/style.css";
```

```js [Web]
import "@blossom-carousel/web/style.css";
```
::

## Component structure

Embla usually needs a viewport element, a container element, and slide elements. With Blossom, the carousel root is the scroll container and the slides are direct children.

::code-group{sync="migration-code-style"}
```vue [Vue]
<script setup lang="ts">
import useEmblaCarousel from "embla-carousel-vue"; // [!code --]
import { BlossomCarousel } from "@blossom-carousel/vue"; // [!code ++]
import "@blossom-carousel/vue/style.css"; // [!code ++]
 
const [emblaRef] = useEmblaCarousel({ align: "start" }); // [!code --]
</script>

<template>
    <div class="embla" ref="emblaRef"> // [!code --]
        <div class="embla__container"> // [!code --]
        <div class="embla__slide">Slide 1</div> // [!code --]
        <div class="embla__slide">Slide 2</div> // [!code --]
        <div class="embla__slide">Slide 3</div> // [!code --]
        </div> // [!code --]
    </div> // [!code --]
    <BlossomCarousel class="carousel"> // [!code ++]
        <div class="slide snap-start">Slide 1</div> // [!code ++]
        <div class="slide snap-start">Slide 2</div> // [!code ++]
        <div class="slide snap-start">Slide 3</div> // [!code ++]
    </BlossomCarousel> // [!code ++]
</template>
```

```tsx [React]
import useEmblaCarousel from "embla-carousel-react"; // [!code --]
import { BlossomCarousel } from "@blossom-carousel/react"; // [!code ++]
import "@blossom-carousel/react/style.css"; // [!code ++]

 export function Carousel() {
  const [emblaRef] = useEmblaCarousel({ align: "start" }); // [!code --]

  return (
    <div className="embla" ref={emblaRef}> {/* [!code --] */}
      <div className="embla__container"> {/* [!code --] */}
        <div className="embla__slide">Slide 1</div> {/* [!code --] */}
        <div className="embla__slide">Slide 2</div> {/* [!code --] */}
        <div className="embla__slide">Slide 3</div> {/* [!code --] */}
      </div> {/* [!code --] */}
    </div> {/* [!code --] */}
    <BlossomCarousel className="carousel"> {/* [!code ++] */}
      <div className="slide snap-start">Slide 1</div> {/* [!code ++] */}
      <div className="slide snap-start">Slide 2</div> {/* [!code ++] */}
      <div className="slide snap-start">Slide 3</div> {/* [!code ++] */}
    </BlossomCarousel> {/* [!code ++] */}
  );
 }
```

```svelte [Svelte]
<script>
  import emblaCarouselSvelte from "embla-carousel-svelte"; // [!code --]
  import { BlossomCarousel } from "@blossom-carousel/svelte"; // [!code ++]
  import "@blossom-carousel/svelte/style.css"; // [!code ++]

  const options = { align: "start" }; // [!code --]
</script>

<div class="embla" use:emblaCarouselSvelte={{ options }}> <!-- [!code --] -->
  <div class="embla__container"> <!-- [!code --] -->
    <div class="embla__slide">Slide 1</div> <!-- [!code --] -->
    <div class="embla__slide">Slide 2</div> <!-- [!code --] -->
    <div class="embla__slide">Slide 3</div> <!-- [!code --] -->
  </div> <!-- [!code --] -->
</div> <!-- [!code --] -->
<BlossomCarousel class="carousel"> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 1</div> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 2</div> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 3</div> <!-- [!code ++] -->
</BlossomCarousel> <!-- [!code ++] -->
```

```html [Core]
<div class="embla"> <!-- [!code --] -->
  <div class="embla__container"> <!-- [!code --] -->
    <div class="embla__slide">Slide 1</div> <!-- [!code --] -->
    <div class="embla__slide">Slide 2</div> <!-- [!code --] -->
    <div class="embla__slide">Slide 3</div> <!-- [!code --] -->
  </div> <!-- [!code --] -->
</div> <!-- [!code --] -->
<div class="carousel"> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 1</div> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 2</div> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 3</div> <!-- [!code ++] -->
</div> <!-- [!code ++] -->

<script type="module">
  import EmblaCarousel from "embla-carousel"; // [!code --]
  import { Blossom } from "@blossom-carousel/core"; // [!code ++]
  import "@blossom-carousel/core/style.css"; // [!code ++]

  const emblaElement = document.querySelector(".embla"); // [!code --]
  const emblaApi = EmblaCarousel(emblaElement, { align: "start" }); // [!code --]

  const carouselElement = document.querySelector(".carousel"); // [!code ++]
  const blossom = Blossom(carouselElement); // [!code ++]
  blossom.init(); // [!code ++]
</script>
```
::

## Options

Embla options describe how the carousel engine should calculate slide positions. In Blossom, those same decisions are usually regular CSS on the scroll container and slides.

| Embla concept      | Blossom approach                                                                                                                                                                                       |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `axis: "x"`        | Automatically handled by Blossom based on native overscroll.                                                                                                                                           |
| `align: "start"`   | Use CSS `scroll-snap-align: start` on slides.                                                                                                                                                          |
| `align: "center"`  | Use CSS `scroll-snap-align: center` on slides.                                                                                                                                                         |
| `containScroll`    | Use native scroll bounds, padding, and `scroll-padding`.                                                                                                                                               |
| `slidesToScroll`   | Use CSS `scroll-snap-align` within `:nth-child(xn)` or nest slides in groups.                                                                                                                          |
| `dragFree`         | Omit `scroll-snap-align` or use `scroll-snap-type: proximity`.                                                                                                                                         |
| `direction: "rtl"` | Use `dir="rtl"` or CSS `direction: rtl`.                                                                                                                                                               |
| `breakpoints`      | Use CSS media queries and container queries.                                                                                                                                                           |
| `loop`             | Prefer bounded native scrolling, or use the experimental repeat pattern when an infinite effect is required. See [Repeat example](https://www.blossom-carousel.com/docs/examples/experimental/repeat). |
| `draggable`        | Use CSS `overflow: hidden` on the carousel to disable dragging and scrolling.                                                                                                                          |

For example, this Embla setup:

```js [Embla]
useEmblaCarousel({
  axis: "x",
  align: "center",
  containScroll: "trimSnaps",
  dragFree: false,
  breakpoints: {
    "(min-width: 768px)": { align: "start" },
  },
});
```

becomes CSS:

```css [Blossom]
.carousel {
  scroll-snap-type: inline mandatory;
  scroll-padding-inline: 1rem;
}

.slide {
  scroll-snap-align: center;
}

@media (min-width: 768px) {
  .slide {
    scroll-snap-align: start;
  }
}
```

## Controls

Embla controls call methods on the Embla API. Blossom provides `<BlossomPrev>`, `<BlossomNext>`, and `<BlossomDots>` components that link to the carousel through matching `id` and `for` props.

```ts
emblaApi.scrollPrev(); // [!code --]
emblaApi.scrollNext(); // [!code --]
```

```html
<BlossomCarousel id="gallery" class="carousel">
  <div data-blossom-slide class="slide">Slide 1</div>
  ...
</BlossomCarousel>

<div class="controls">
  <BlossomPrev for="gallery" />
  <BlossomNext for="gallery" />
</div>

<BlossomDots for="gallery" />
```

For direct slide navigation, use native scrolling on the target slide.

```ts
slides[index].scrollIntoView({
  behavior: "smooth",
  inline: "center",
  block: "nearest",
});
```

## API

Embla commonly uses `select` events and `selectedScrollSnap()` to track the active slide.

With Blossom, the carousel is a real scroll container, so use browser APIs such as `IntersectionObserver`, `scrollsnapchange`, or `scroll` events depending on the browser support you need.

```ts
emblaApi.on("select", () => { // [!code --]
  setSelectedIndex(emblaApi.selectedScrollSnap()); // [!code --]
}); // [!code --]

carousel.addEventListener("scrollsnapchange", (event) => { // [!code ++]
  setSelectedIndex(event.detail.index); // [!code ++]
}); // [!code ++]

Or use IntersectionObserver for wider browser support

const slides = Array.from(carousel.children); // [!code ++]
const observer = new IntersectionObserver( // [!code ++]
  (entries) => { // [!code ++]
    const activeEntry = entries.find((entry) => entry.isIntersecting); // [!code ++]
    if (activeEntry) { // [!code ++]
      const index = slides.indexOf(activeEntry.target); // [!code ++]
      setSelectedIndex(index); // [!code ++]
    } // [!code ++]
  }, // [!code ++]
  { root: carousel, threshold: 0.5 }, // [!code ++]
); // [!code ++]
slides.forEach((slide) => observer.observe(slide)); // [!code ++]
```

## Plugins

Embla plugins usually become either small Blossom wrappers or native platform features.

| Embla plugin pattern | Blossom replacement                                                      |
| -------------------- | ------------------------------------------------------------------------ |
| Autoplay             | Use manual timer that scrolls the next slide into view.                  |
| Fade                 | Use CSS scroll-driven animations or intersection state.                  |
| Auto height          | Let content define height, or update layout with `ResizeObserver`.       |
| Class names          | Use `IntersectionObserver`, `scrollsnapchange`, or scroll-state queries. |
| Wheel gestures       | Use the browser's native scroll behavior where possible.                 |

Keep plugin migrations small. Start from a working Blossom carousel, then add the behavior back only if the product still needs it.

## Lifecycle

Embla's and Blossom's lifecycle methods are similar.

::note{color="neutral" icon="i-lucide-lightbulb"}
Blossom initializes automatically when using framework components.
::

```ts
const [emblaRef, emblaApi] = useEmblaCarousel(); // [!code --]
emblaApi.reInit(); // [!code --]
emblaApi.destroy(); // [!code --]
const blossom = Blossom(carouselElement); // [!code ++]
blossom.init(); // [!code ++]
blossom.destroy(); // [!code ++]
```

## Migration checklist

- Remove Embla packages and install the matching Blossom package.
- Import the stylesheet from your framework package once (for example `@blossom-carousel/vue/style.css`).
- Replace Embla viewport and container markup with `<BlossomCarousel>` and direct slide children.
- Move slide sizing, alignment, gaps, snapping, direction, and breakpoints into CSS.
- Replace `scrollPrev()` and `scrollNext()` with `<BlossomPrev>` and `<BlossomNext>`.
- Replace `scrollTo()` with `scrollIntoView()` or native `scrollTo()` on the carousel element.
- Replace `select` listeners with browser observers or scroll snap events.
- Rebuild only the Embla plugins your carousel still needs.

## Next steps

- [Installation](https://www.blossom-carousel.com/docs/getting-started/installation) - Pick the package for your framework.
- [Snapping](https://www.blossom-carousel.com/docs/examples/basic/snap) - Configure scroll snap behavior with CSS.
- [Buttons](https://www.blossom-carousel.com/docs/examples/basic/buttons) - Add previous and next controls.
- [Dots](https://www.blossom-carousel.com/docs/examples/basic/dots) - Add dot markers with `<BlossomDots>`.
- [Repeat](https://www.blossom-carousel.com/docs/examples/experimental/repeat) - Explore an experimental repeating carousel pattern.


# Swiper

Swiper provides a large carousel system with framework components, modules, configuration options, lifecycle events, and built-in effects.

Blossom keeps the carousel as a native scroll container. Layout, snapping, spacing, breakpoints, and many effects move back into CSS, while Blossom adds dragging and small convenience methods.

## Migration mindset

When moving from Swiper to Blossom, migrate the carousel in three steps:

1. Replace `<Swiper>` and `<SwiperSlide>` with a single `<BlossomCarousel>` root and direct children.
2. Move Swiper options such as `slidesPerView`, `spaceBetween`, `direction`, and `breakpoints` into CSS.
3. Replace Swiper modules and events with Blossom methods, native scroll APIs, and browser observers.

::note{color="neutral" icon="i-lucide-lightbulb"}
Most Swiper migrations become smaller when you start with the markup and CSS first, then add back only the behavior the product still needs.
::

## Installation

Remove Swiper and install the matching Blossom package for your framework.

::code-group{sync="migration-code-style"}
```bash [Vue]
npm uninstall swiper
npm install @blossom-carousel/vue
```

```bash [React]
npm uninstall swiper
npm install @blossom-carousel/react
```

```bash [Svelte]
npm uninstall swiper
npm install @blossom-carousel/svelte
```

```bash [Core]
npm uninstall swiper
npm install @blossom-carousel/core
```
::

Import the stylesheet from your framework package once in your app.

::code-group
```js [Vue]
import "@blossom-carousel/vue/style.css";
```

```js [React]
import "@blossom-carousel/react/style.css";
```

```js [Svelte]
import "@blossom-carousel/svelte/style.css";
```

```js [Core]
import "@blossom-carousel/core/style.css";
```

```js [Web]
import "@blossom-carousel/web/style.css";
```
::

## Component structure

Swiper wraps slides in framework-specific components. Blossom uses the carousel root as the scroll container and treats direct children as slides.

::code-group{sync="migration-code-style"}
```vue [Vue]
<script setup lang="ts">
import { Swiper, SwiperSlide } from "swiper/vue"; // [!code --]
import "swiper/css"; // [!code --]
import { BlossomCarousel } from "@blossom-carousel/vue"; // [!code ++]
import "@blossom-carousel/vue/style.css"; // [!code ++]
</script>

<template>
  <Swiper :slides-per-view="4" :space-between="16"> <!-- [!code --] -->
    <SwiperSlide>Slide 1</SwiperSlide> <!-- [!code --] -->
    <SwiperSlide>Slide 2</SwiperSlide> <!-- [!code --] -->
    <SwiperSlide>Slide 3</SwiperSlide> <!-- [!code --] -->
  </Swiper> <!-- [!code --] -->
  <BlossomCarousel class="carousel grid! grid-auto-cols grid-cols-[25%] gap-4"> <!-- [!code ++] -->
    <div class="slide snap-center">Slide 1</div> <!-- [!code ++] -->
    <div class="slide snap-center">Slide 2</div> <!-- [!code ++] -->
    <div class="slide snap-center">Slide 3</div> <!-- [!code ++] -->
  </BlossomCarousel> <!-- [!code ++] -->
</template>
```

```tsx [React]
import { Swiper, SwiperSlide } from "swiper/react"; // [!code --]
import "swiper/css"; // [!code --]
import { BlossomCarousel } from "@blossom-carousel/react"; // [!code ++]
import "@blossom-carousel/react/style.css"; // [!code ++]

export function Carousel() {
  return (
    <Swiper slidesPerView={1.25} spaceBetween={16}> {/* [!code --] */}
      <SwiperSlide>Slide 1</SwiperSlide> {/* [!code --] */}
      <SwiperSlide>Slide 2</SwiperSlide> {/* [!code --] */}
      <SwiperSlide>Slide 3</SwiperSlide> {/* [!code --] */}
    </Swiper> {/* [!code --] */}
    <BlossomCarousel className="carousel grid! grid-auto-cols grid-cols-[25%] gap-4"> {/* [!code ++] */}
      <div className="slide snap-start">Slide 1</div> {/* [!code ++] */}
      <div className="slide snap-start">Slide 2</div> {/* [!code ++] */}
      <div className="slide snap-start">Slide 3</div> {/* [!code ++] */}
    </BlossomCarousel> {/* [!code ++] */}
  );
}
```

```svelte [Svelte]
<script>
  import { Swiper, SwiperSlide } from "swiper/svelte"; // [!code --]
  import "swiper/css"; // [!code --]
  import { BlossomCarousel } from "@blossom-carousel/svelte"; // [!code ++]
  import "@blossom-carousel/svelte/style.css"; // [!code ++]
</script>

<Swiper slidesPerView={1.25} spaceBetween={16}> <!-- [!code --] -->
  <SwiperSlide>Slide 1</SwiperSlide> <!-- [!code --] -->
  <SwiperSlide>Slide 2</SwiperSlide> <!-- [!code --] -->
  <SwiperSlide>Slide 3</SwiperSlide> <!-- [!code --] -->
</Swiper> <!-- [!code --] -->
<BlossomCarousel class="carousel grid! grid-auto-cols grid-cols-[25%] gap-4"> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 1</div> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 2</div> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 3</div> <!-- [!code ++] -->
</BlossomCarousel> <!-- [!code ++] -->
```

```html [Core]
<div class="swiper"> <!-- [!code --] -->
  <div class="swiper-wrapper"> <!-- [!code --] -->
    <div class="swiper-slide">Slide 1</div> <!-- [!code --] -->
    <div class="swiper-slide">Slide 2</div> <!-- [!code --] -->
    <div class="swiper-slide">Slide 3</div> <!-- [!code --] -->
  </div> <!-- [!code --] -->
</div> <!-- [!code --] -->
<div class="carousel grid! grid-auto-cols grid-cols-[25%] gap-4"> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 1</div> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 2</div> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 3</div> <!-- [!code ++] -->
</div> <!-- [!code ++] -->

<script type="module">
  import Swiper from "swiper"; // [!code --]
  import "swiper/css"; // [!code --]
  import { Blossom } from "@blossom-carousel/core"; // [!code ++]
  import "@blossom-carousel/core/style.css"; // [!code ++]

  const swiper = new Swiper(".swiper", { // [!code --]
    slidesPerView: 1.25, // [!code --]
    spaceBetween: 16, // [!code --]
  }); // [!code --]

  const carouselElement = document.querySelector(".carousel"); // [!code ++]
  const blossom = Blossom(carouselElement); // [!code ++]
  blossom.init(); // [!code ++]
</script>
```
::

## Options

Swiper options describe how its engine should size slides, attach modules, and calculate movement. In Blossom, most of those choices become CSS or small browser APIs.

| Swiper concept            | Blossom approach                                                                                                                                                                                       |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `slidesPerView`           | Use CSS `grid-auto-columns` to define the relative width of slides.                                                                                                                                    |
| `spaceBetween`            | Use CSS `gap` in a `grid` or `flex` layout.                                                                                                                                                            |
| `direction: "horizontal"` | Automatically handled by Blossom based on native overscroll.                                                                                                                                           |
| `centeredSlides`          | Use CSS `scroll-snap-align: center` on slides.                                                                                                                                                         |
| `breakpoints`             | Use CSS media queries and container queries.                                                                                                                                                           |
| `loop`                    | Prefer bounded native scrolling, or use the experimental repeat pattern when an infinite effect is required. See [Repeat example](https://www.blossom-carousel.com/docs/examples/experimental/repeat). |
| `freeMode`                | Omit `scroll-snap-align` or use `scroll-snap-type: proximity`.                                                                                                                                         |
| `allowTouchMove`          | Use CSS `overflow: hidden` on the carousel to disable dragging and scrolling.                                                                                                                          |
| `effect` modules          | Use CSS transforms, scroll-driven animations, or intersection state.                                                                                                                                   |

For example, this Swiper setup:

```js [Swiper]
const swiperOptions = {
  slidesPerView: 1,
  spaceBetween: 16,
  centeredSlides: false,
  breakpoints: {
    768: { slidesPerView: 3, centeredSlides: true },
  },
};
```

becomes CSS:

```css [Blossom]
.carousel {
  display: grid;
  grid-auto-flow: column;
  grid-auto-columns: 100%;
  gap: 1rem;
  scroll-snap-type: inline mandatory;
}

.slide {
  scroll-snap-align: start;
}

@media (min-width: 768px) {
  .carousel {
    grid-auto-columns: calc((100% - 2rem) / 3);
  }

  .slide {
    scroll-snap-align: center;
  }
}
```

## Controls

Swiper controls call methods on a Swiper instance. Blossom provides `<BlossomPrev>`, `<BlossomNext>`, and `<BlossomDots>` components that link to the carousel through matching `id` and `for` props.

```ts
swiper.slidePrev(); // [!code --]
swiper.slideNext(); // [!code --]
```

```html
<BlossomCarousel id="gallery" class="carousel">
  <div data-blossom-slide class="slide">Slide 1</div>
  ...
</BlossomCarousel>

<div class="controls">
  <BlossomPrev for="gallery" />
  <BlossomNext for="gallery" />
</div>

<BlossomDots for="gallery" />
```

For direct slide navigation, use native scrolling on the target slide.

```ts
slides[index].scrollIntoView({
  behavior: "smooth",
  inline: "center",
  block: "nearest",
});
```

## API

Swiper commonly uses events such as `slideChange` and properties such as `activeIndex`.

With Blossom, the carousel is a real scroll container, so use browser APIs such as `IntersectionObserver`, `scrollsnapchange`, or `scroll` events depending on the browser support you need.

```ts
swiper.on("slideChange", () => { // [!code --]
  setSelectedIndex(swiper.activeIndex); // [!code --]
}); // [!code --]

carousel.addEventListener("scrollsnapchange", (event) => { // [!code ++]
  setSelectedIndex(event.detail.index); // [!code ++]
}); // [!code ++]

Or use IntersectionObserver for wider browser support

const slides = Array.from(carousel.children); // [!code ++]
const observer = new IntersectionObserver( // [!code ++]
  (entries) => { // [!code ++]
    const activeEntry = entries.find((entry) => entry.isIntersecting); // [!code ++]
    if (activeEntry) { // [!code ++]
      setSelectedIndex(slides.indexOf(activeEntry.target)); // [!code ++]
    } // [!code ++]
  }, // [!code ++]
  { root: carousel, threshold: 0.5 }, // [!code ++]
); // [!code ++]
slides.forEach((slide) => observer.observe(slide)); // [!code ++]
```

## Modules

Swiper modules usually become either native browser features or small code that calls Blossom methods.

| Swiper module pattern           | Blossom replacement                                   |
| ------------------------------- | ----------------------------------------------------- |
| Navigation                      | `<BlossomPrev>` and `<BlossomNext>` components.       |
| Pagination                      | `<BlossomDots>` with `data-blossom-slide` on slides.  |
| Autoplay                        | A manual timer that scrolls the next slide into view. |
| Keyboard                        | Handled natively by the browser.                      |
| Mousewheel                      | Native scrolling where possible.                      |
| Grid                            | CSS grid.                                             |
| Effect Fade / Cards / Coverflow | CSS scroll-driven animations or intersection state.   |

Start with a working native-scroll carousel before rebuilding effects. Many Swiper effects are visual polish, not required carousel mechanics.

## Lifecycle

Swipers's and Blossom's lifecycle methods are similar.

::note{color="neutral" icon="i-lucide-lightbulb"}
Blossom initializes automatically when using framework components.
::

```ts
swiper.update(); // [!code --]
swiper.destroy(); // [!code --]
blossom.init(); // [!code ++]
blossom.destroy(); // [!code ++]
```

## Migration checklist

- Remove Swiper packages and install the matching Blossom package.
- Import the stylesheet from your framework package once (for example `@blossom-carousel/vue/style.css`).
- Replace `<Swiper>` and `<SwiperSlide>` with `<BlossomCarousel>` and direct slide children.
- Move slide sizing, gaps, snapping, direction, and breakpoints into CSS.
- Replace `slidePrev()` and `slideNext()` with `<BlossomPrev>` and `<BlossomNext>`.
- Replace `slideTo()` with `scrollIntoView()` or native `scrollTo()`.
- Replace Swiper events with browser observers or scroll snap events.
- Rebuild only the Swiper modules your carousel still needs.

## Next steps

- [Installation](https://www.blossom-carousel.com/docs/getting-started/installation) - Pick the package for your framework.
- [Snapping](https://www.blossom-carousel.com/docs/examples/basic/snap) - Configure scroll snap behavior with CSS.
- [Buttons](https://www.blossom-carousel.com/docs/examples/basic/buttons) - Add previous and next controls.
- [Dots](https://www.blossom-carousel.com/docs/examples/basic/dots) - Add dot markers with `<BlossomDots>`.
- [Repeat](https://www.blossom-carousel.com/docs/examples/experimental/repeat) - Explore an experimental repeating carousel pattern.


# Splide

Splide builds a carousel from a root element, track, list, slide elements, options, extensions, and a JavaScript instance.

Blossom keeps the carousel as a native scroll container. Layout, slide sizing, gaps, snapping, and responsive behavior belong in CSS, while Blossom adds dragging and small convenience methods.

## Migration mindset

When moving from Splide to Blossom, migrate the carousel in three steps:

1. Replace the Splide root, track, and list structure with a single `<BlossomCarousel>` root.
2. Move Splide options such as `perPage`, `gap`, `focus`, `direction`, and `breakpoints` into CSS.
3. Replace Splide instance calls and events with Blossom methods, native scroll APIs, and browser observers.

::note{color="neutral" icon="i-lucide-lightbulb"}
Splide migrations usually remove wrapper markup. The Blossom carousel root is the element that scrolls.
::

## Installation

Remove Splide and install the matching Blossom package for your framework.

::code-group{sync="migration-code-style"}
```bash [Vue]
npm uninstall @splidejs/vue-splide @splidejs/splide
npm install @blossom-carousel/vue
```

```bash [React]
npm uninstall @splidejs/react-splide @splidejs/splide
npm install @blossom-carousel/react
```

```bash [Svelte]
npm uninstall @splidejs/svelte-splide @splidejs/splide
npm install @blossom-carousel/svelte
```

```bash [Core]
npm uninstall @splidejs/splide
npm install @blossom-carousel/core
```
::

Import the stylesheet from your framework package once in your app.

::code-group
```js [Vue]
import "@blossom-carousel/vue/style.css";
```

```js [React]
import "@blossom-carousel/react/style.css";
```

```js [Svelte]
import "@blossom-carousel/svelte/style.css";
```

```js [Core]
import "@blossom-carousel/core/style.css";
```

```js [Web]
import "@blossom-carousel/web/style.css";
```
::

## Component structure

Splide usually needs a root, track, list, and slide elements. Blossom uses one scroll container with direct slide children.

::code-group{sync="migration-code-style"}
```vue [Vue]
<script setup lang="ts">
import { Splide, SplideSlide } from "@splidejs/vue-splide"; // [!code --]
import "@splidejs/vue-splide/css"; // [!code --]
import { BlossomCarousel } from "@blossom-carousel/vue"; // [!code ++]
import "@blossom-carousel/vue/style.css"; // [!code ++]
</script>

<template>
  <Splide :options="{ perPage: 4, gap: '1rem' }"> <!-- [!code --] -->
    <SplideSlide>Slide 1</SplideSlide> <!-- [!code --] -->
    <SplideSlide>Slide 2</SplideSlide> <!-- [!code --] -->
    <SplideSlide>Slide 3</SplideSlide> <!-- [!code --] -->
  </Splide> <!-- [!code --] -->
  <BlossomCarousel class="carousel grid! grid-auto-cols grid-cols-[calc((100% - 3rem) / 4)] gap-4"> <!-- [!code ++] -->
    <div class="slide snap-start">Slide 1</div> <!-- [!code ++] -->
    <div class="slide snap-start">Slide 2</div> <!-- [!code ++] -->
    <div class="slide snap-start">Slide 3</div> <!-- [!code ++] -->
  </BlossomCarousel> <!-- [!code ++] -->
</template>
```

```tsx [React]
import { Splide, SplideSlide } from "@splidejs/react-splide"; // [!code --]
import "@splidejs/react-splide/css"; // [!code --]
import { BlossomCarousel } from "@blossom-carousel/react"; // [!code ++]
import "@blossom-carousel/react/style.css"; // [!code ++]

export function Carousel() {
  return (
    <Splide options={{ perPage: 4, gap: "1rem" }}> {/* [!code --] */}
      <SplideSlide>Slide 1</SplideSlide> {/* [!code --] */}
      <SplideSlide>Slide 2</SplideSlide> {/* [!code --] */}
      <SplideSlide>Slide 3</SplideSlide> {/* [!code --] */}
    </Splide> {/* [!code --] */}
    <BlossomCarousel className="carousel grid! grid-auto-cols grid-cols-[calc((100% - 3rem) / 4)] gap-4"> {/* [!code ++] */}
      <div className="slide snap-start">Slide 1</div> {/* [!code ++] */}
      <div className="slide snap-start">Slide 2</div> {/* [!code ++] */}
      <div className="slide snap-start">Slide 3</div> {/* [!code ++] */}
    </BlossomCarousel> {/* [!code ++] */}
  );
}
```

```svelte [Svelte]
<script>
  import { Splide, SplideSlide } from "@splidejs/svelte-splide"; // [!code --]
  import "@splidejs/svelte-splide/css"; // [!code --]
  import { BlossomCarousel } from "@blossom-carousel/svelte"; // [!code ++]
  import "@blossom-carousel/svelte/style.css"; // [!code ++]

  const options = { perPage: 4, gap: "1rem" }; // [!code --]
</script>

<Splide {options}> <!-- [!code --] -->
  <SplideSlide>Slide 1</SplideSlide> <!-- [!code --] -->
  <SplideSlide>Slide 2</SplideSlide> <!-- [!code --] -->
  <SplideSlide>Slide 3</SplideSlide> <!-- [!code --] -->
</Splide> <!-- [!code --] -->
<BlossomCarousel class="carousel grid! grid-auto-cols grid-cols-[calc((100% - 3rem) / 4)] gap-4"> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 1</div> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 2</div> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 3</div> <!-- [!code ++] -->
</BlossomCarousel> <!-- [!code ++] -->
```

```html [Core]
<div class="splide"> <!-- [!code --] -->
  <div class="splide__track"> <!-- [!code --] -->
    <ul class="splide__list"> <!-- [!code --] -->
      <li class="splide__slide">Slide 1</li> <!-- [!code --] -->
      <li class="splide__slide">Slide 2</li> <!-- [!code --] -->
      <li class="splide__slide">Slide 3</li> <!-- [!code --] -->
    </ul> <!-- [!code --] -->
  </div> <!-- [!code --] -->
</div> <!-- [!code --] -->
<blossom-carousel class="carousel grid! grid-auto-cols grid-cols-[calc((100% - 3rem) / 4)] gap-4"> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 1</div> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 2</div> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 3</div> <!-- [!code ++] -->
</blossom-carousel> <!-- [!code ++] -->
```
::

## Options

Splide options describe slide movement, sizing, and generated controls. In Blossom, those choices usually become CSS and small browser APIs.

| Splide concept    | Blossom approach                                                                                                                                                                                       |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `perPage`         | Use CSS `grid-auto-columns` to define the relative width of slides.                                                                                                                                    |
| `perMove`         | Use CSS `scroll-snap-align` within `:nth-child(xn)` or nest slides in groups.                                                                                                                          |
| `gap`             | Use CSS `gap` in a `grid` or `flex` layout.                                                                                                                                                            |
| `focus: "center"` | Use `scroll-snap-align: center`.                                                                                                                                                                       |
| `direction`       | Use `dir="rtl"` or CSS `direction: rtl`.                                                                                                                                                               |
| `breakpoints`     | Use CSS media queries and container queries.                                                                                                                                                           |
| `type: "loop"`    | Prefer bounded native scrolling, or use the experimental repeat pattern when an infinite effect is required. See [Repeat example](https://www.blossom-carousel.com/docs/examples/experimental/repeat). |
| `drag: "free"`    | Omit `scroll-snap-align` or use `scroll-snap-type: proximity`.                                                                                                                                         |
| `arrows`          | Use `<BlossomPrev>` and `<BlossomNext>`. See [Buttons example](https://www.blossom-carousel.com/docs/examples/basic/buttons).                                                                          |
| `pagination`      | Use `<BlossomDots for="my-carousel">` and mark slides with `data-blossom-slide`. See [Dots example](https://www.blossom-carousel.com/docs/examples/basic/dots).                                        |

For example, this Splide setup:

```js [Splide]
new Splide(".splide", {
  perPage: 1,
  gap: "1rem",
  focus: "center",
  breakpoints: {
    768: { perPage: 3 },
  },
}).mount();
```

becomes CSS:

```css [Blossom]
.carousel {
  display: grid;
  grid-auto-flow: column;
  grid-auto-columns: 100%;
  gap: 1rem;
  scroll-snap-type: inline mandatory;
}

.slide {
  scroll-snap-align: center;
}

@media (min-width: 768px) {
  .carousel {
    grid-auto-columns: calc((100% - 2rem) / 3);
  }
}
```

## Controls

Splide controls call methods on the Splide instance. Blossom provides `<BlossomPrev>`, `<BlossomNext>`, and `<BlossomDots>` components that link to the carousel through matching `id` and `for` props.

```ts
splide.go("<"); // [!code --]
splide.go(">"); // [!code --]
```

```html
<BlossomCarousel id="gallery" class="carousel">
  <div data-blossom-slide class="slide">Slide 1</div>
  ...
</BlossomCarousel>

<div class="controls">
  <BlossomPrev for="gallery" />
  <BlossomNext for="gallery" />
</div>

<BlossomDots for="gallery" />
```

For direct slide navigation, use native scrolling on the target slide.

```ts
slides[index].scrollIntoView({
  behavior: "smooth",
  inline: "center",
  block: "nearest",
});
```

## API

Splide commonly uses `moved` or `active` events to track the current slide.

With Blossom, the carousel is a real scroll container, so use browser APIs such as `IntersectionObserver`, `scrollsnapchange`, or `scroll` events depending on the browser support you need.

```ts
splide.on("moved", (newIndex) => { // [!code --]
  setSelectedIndex(newIndex); // [!code --]
}); // [!code --]

carousel.addEventListener("scrollsnapchange", (event) => { // [!code ++]
  setSelectedIndex(event.detail.index); // [!code ++]
}); // [!code ++]

Or use IntersectionObserver for wider browser support

const slides = Array.from(carousel.children); // [!code ++]
const observer = new IntersectionObserver( // [!code ++]
  (entries) => { // [!code ++]
    const activeEntry = entries.find((entry) => entry.isIntersecting); // [!code ++]
    if (activeEntry) { // [!code ++]
      setSelectedIndex(slides.indexOf(activeEntry.target)); // [!code ++]
    } // [!code ++]
  }, // [!code ++]
  { root: carousel, threshold: 0.5 }, // [!code ++]
); // [!code ++]
slides.forEach((slide) => observer.observe(slide)); // [!code ++]
```

## Extensions

Splide extensions and built-in UI usually become small Blossom wrappers or native platform features.

| Splide pattern | Blossom replacement                                                |
| -------------- | ------------------------------------------------------------------ |
| Arrows         | `<BlossomPrev>` and `<BlossomNext>` components.                    |
| Pagination     | `<BlossomDots>` with `data-blossom-slide` on slides.               |
| Autoplay       | A manual timer that scrolls the next slide into view.              |
| Auto width     | Let slide content size itself with CSS.                            |
| Auto height    | Let content define height, or update layout with `ResizeObserver`. |
| Grid / rows    | CSS grid.                                                          |
| Lazy load      | Native `loading="lazy"` and `content-visibility: auto`.            |

Keep extension migrations small. Start from a working Blossom carousel, then add behavior only if the product still needs it.

## Lifecycle

Splide's and Blossom's lifecycle methods are similar.

::note{color="neutral" icon="i-lucide-lightbulb"}
Blossom initializes automatically when using framework components.
::

```ts
splide.refresh(); // [!code --]
splide.destroy(); // [!code --]
blossom.init(); // [!code ++]
blossom.destroy(); // [!code ++]
```

## Migration checklist

- Remove Splide packages and install the matching Blossom package.
- Import the stylesheet from your framework package once (for example `@blossom-carousel/vue/style.css`).
- Replace Splide root, track, list, and slide wrappers with `<BlossomCarousel>` and direct slide children.
- Move slide sizing, gaps, snapping, direction, focus, and breakpoints into CSS.
- Replace `go("<")` and `go(">")` with `<BlossomPrev>` and `<BlossomNext>`.
- Replace `go(index)` with `scrollIntoView()` or native `scrollTo()`.
- Replace Splide events with browser observers or scroll snap events.
- Rebuild only the Splide extensions your carousel still needs.

## Next steps

- [Installation](https://www.blossom-carousel.com/docs/getting-started/installation) - Pick the package for your framework.
- [Snapping](https://www.blossom-carousel.com/docs/examples/basic/snap) - Configure scroll snap behavior with CSS.
- [Buttons](https://www.blossom-carousel.com/docs/examples/basic/buttons) - Add previous and next controls.
- [Dots](https://www.blossom-carousel.com/docs/examples/basic/dots) - Add dot markers with `<BlossomDots>`.
- [Repeat](https://www.blossom-carousel.com/docs/examples/experimental/repeat) - Explore an experimental repeating carousel pattern.


# Slick

Slick Carousel creates a carousel around jQuery-managed markup, cloned slides, option objects, generated controls, and event callbacks. React Slick wraps the same model in React components.

Blossom keeps the carousel as a native scroll container. Layout, slide sizing, gaps, breakpoints, and snapping belong in CSS, while Blossom adds dragging and small convenience methods.

## Migration mindset

When moving from Slick Carousel to Blossom, migrate the carousel in three steps:

1. Replace Slick's generated track/list structure with a single `<BlossomCarousel>` root and direct children.
2. Move Slick options such as `slidesToShow`, `slidesToScroll`, `centerMode`, and `responsive` into CSS.
3. Replace Slick method calls and events with Blossom methods, native scroll APIs, and browser observers.

::note{color="neutral" icon="i-lucide-lightbulb"}
Slick often adds hidden markup and cloned slides. With Blossom, your source markup is the carousel markup.
::

## Installation

Remove Slick packages and install the matching Blossom package for your framework.

::code-group{sync="migration-code-style"}
```bash [Vue]
npm uninstall vue-slick-carousel slick-carousel
npm install @blossom-carousel/vue
```

```bash [React]
npm uninstall react-slick slick-carousel
npm install @blossom-carousel/react
```

```bash [Svelte]
npm uninstall slick-carousel jquery
npm install @blossom-carousel/svelte
```

```bash [Core]
npm uninstall slick-carousel jquery
npm install @blossom-carousel/core
```
::

Import the stylesheet from your framework package once in your app.

::code-group
```js [Vue]
import "@blossom-carousel/vue/style.css";
```

```js [React]
import "@blossom-carousel/react/style.css";
```

```js [Svelte]
import "@blossom-carousel/svelte/style.css";
```

```js [Core]
import "@blossom-carousel/core/style.css";
```

```js [Web]
import "@blossom-carousel/web/style.css";
```
::

## Component structure

Slick and React Slick wrap your slides in a generated list and track. Blossom uses one scroll container with direct slide children.

::code-group{sync="migration-code-style"}
```vue [Vue]
<script setup lang="ts">
import VueSlickCarousel from "vue-slick-carousel"; // [!code --]
import "vue-slick-carousel/dist/vue-slick-carousel.css"; // [!code --]
import { BlossomCarousel } from "@blossom-carousel/vue"; // [!code ++]
import "@blossom-carousel/vue/style.css"; // [!code ++]

const slickSettings = { slidesToShow: 4, slidesToScroll: 1 }; // [!code --]
</script>

<template>
  <VueSlickCarousel v-bind="slickSettings"> <!-- [!code --] -->
    <div>Slide 1</div> <!-- [!code --] -->
    <div>Slide 2</div> <!-- [!code --] -->
    <div>Slide 3</div> <!-- [!code --] -->
  </VueSlickCarousel> <!-- [!code --] -->
  <BlossomCarousel class="carousel grid! grid-auto-cols grid-cols-[calc((100% - 3rem) / 4)] gap-4"> <!-- [!code ++] -->
    <div class="slide snap-start">Slide 1</div> <!-- [!code ++] -->
    <div class="slide snap-start">Slide 2</div> <!-- [!code ++] -->
    <div class="slide snap-start">Slide 3</div> <!-- [!code ++] -->
  </BlossomCarousel> <!-- [!code ++] -->
</template>
```

```tsx [React]
import Slider from "react-slick"; // [!code --]
import "slick-carousel/slick/slick.css"; // [!code --]
import { BlossomCarousel } from "@blossom-carousel/react"; // [!code ++]
import "@blossom-carousel/react/style.css"; // [!code ++]

export function Carousel() {
  return (
    <Slider slidesToShow={4} slidesToScroll={1}> {/* [!code --] */}
      <div>Slide 1</div> {/* [!code --] */}
      <div>Slide 2</div> {/* [!code --] */}
      <div>Slide 3</div> {/* [!code --] */}
    </Slider> {/* [!code --] */}
    <BlossomCarousel className="carousel grid! grid-auto-cols grid-cols-[calc((100% - 3rem) / 4)] gap-4"> {/* [!code ++] */}
      <div className="slide snap-start">Slide 1</div> {/* [!code ++] */}
      <div className="slide snap-start">Slide 2</div> {/* [!code ++] */}
      <div className="slide snap-start">Slide 3</div> {/* [!code ++] */}
    </BlossomCarousel> {/* [!code ++] */}
  );
}
```

```svelte [Svelte]
<script>
  import { onMount } from "svelte"; // [!code --]
  import $ from "jquery"; // [!code --]
  import "slick-carousel"; // [!code --]
  import "slick-carousel/slick/slick.css"; // [!code --]
  import { BlossomCarousel } from "@blossom-carousel/svelte"; // [!code ++]
  import "@blossom-carousel/svelte/style.css"; // [!code ++]

  let carousel; // [!code --]

  onMount(() => { // [!code --]
    const slick = $(carousel).slick({ slidesToShow: 4, slidesToScroll: 1 }); // [!code --]
    return () => slick.slick("unslick"); // [!code --]
  }); // [!code --]
</script>

<div class="carousel" bind:this={carousel}> <!-- [!code --] -->
  <div>Slide 1</div> <!-- [!code --] -->
  <div>Slide 2</div> <!-- [!code --] -->
  <div>Slide 3</div> <!-- [!code --] -->
</div> <!-- [!code --] -->
<BlossomCarousel class="carousel grid! grid-auto-cols grid-cols-[calc((100% - 3rem) / 4)] gap-4"> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 1</div> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 2</div> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 3</div> <!-- [!code ++] -->
</BlossomCarousel> <!-- [!code ++] -->
```

```html [jQuery]
<div class="carousel"> <!-- [!code --] -->
  <div>Slide 1</div> <!-- [!code --] -->
  <div>Slide 2</div> <!-- [!code --] -->
  <div>Slide 3</div> <!-- [!code --] -->
</div> <!-- [!code --] -->
<blossom-carousel class="carousel grid! grid-auto-cols grid-cols-[calc((100% - 3rem) / 4)] gap-4"> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 1</div> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 2</div> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 3</div> <!-- [!code ++] -->
</blossom-carousel> <!-- [!code ++] -->
```
::

## Options

Slick options describe how its track should move, clone slides, and generate UI. In Blossom, most of those choices become CSS or small browser APIs.

| Slick concept         | Blossom approach                                                                                                                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `slidesToShow`        | Use CSS `grid-auto-columns` to define the relative width of slides.                                                                                                                                    |
| `slidesToScroll`      | Use CSS `scroll-snap-align` within `:nth-child(xn)` or nest slides in groups.                                                                                                                          |
| `centerMode`          | Use `scroll-snap-align: center`.                                                                                                                                                                       |
| `variableWidth`       | Let slides size themselves with CSS.                                                                                                                                                                   |
| `adaptiveHeight`      | Let content define height, or update layout with `ResizeObserver`.                                                                                                                                     |
| `responsive`          | Use CSS media queries and container queries.                                                                                                                                                           |
| `infinite`            | Prefer bounded native scrolling, or use the experimental repeat pattern when an infinite effect is required. See [Repeat example](https://www.blossom-carousel.com/docs/examples/experimental/repeat). |
| `draggable` / `swipe` | Use CSS `overflow: hidden` on the carousel to disable dragging and scrolling.                                                                                                                          |
| `arrows`              | Use `<BlossomPrev>` and `<BlossomNext>`. See [Buttons example](https://www.blossom-carousel.com/docs/examples/basic/buttons).                                                                          |
| `dots`                | Use `<BlossomDots for="my-carousel">` and mark slides with `data-blossom-slide`. See [Dots example](https://www.blossom-carousel.com/docs/examples/basic/dots).                                        |

For example, this Slick setup:

```js [Slick]
$(".carousel").slick({
  slidesToShow: 1,
  slidesToScroll: 1,
  centerMode: true,
  responsive: [{ breakpoint: 768, settings: { slidesToShow: 3 } }],
});
```

becomes CSS:

```css [Blossom]
.carousel {
  display: grid;
  grid-auto-flow: column;
  grid-auto-columns: 100%;
  gap: 1rem;
  scroll-snap-type: inline mandatory;
}

.slide {
  scroll-snap-align: center;
}

@media (min-width: 768px) {
  .carousel {
    grid-auto-columns: calc((100% - 2rem) / 3);
  }
}
```

## Controls

Slick controls call methods on the Slick instance. Blossom provides `<BlossomPrev>`, `<BlossomNext>`, and `<BlossomDots>` components that link to the carousel through matching `id` and `for` props.

```ts
$(".carousel").slick("slickPrev"); // [!code --]
$(".carousel").slick("slickNext"); // [!code --]
```

```html
<BlossomCarousel id="gallery" class="carousel">
  <div data-blossom-slide class="slide">Slide 1</div>
  ...
</BlossomCarousel>

<div class="controls">
  <BlossomPrev for="gallery" />
  <BlossomNext for="gallery" />
</div>

<BlossomDots for="gallery" />
```

For direct slide navigation, use native scrolling on the target slide.

```ts
slides[index].scrollIntoView({
  behavior: "smooth",
  inline: "center",
  block: "nearest",
});
```

## API

Slick commonly uses `afterChange` to track the current slide.

With Blossom, the carousel is a real scroll container, so use browser APIs such as `IntersectionObserver`, `scrollsnapchange`, or `scroll` events depending on the browser support you need.

```ts
$(".carousel").on("afterChange", (_event, _slick, currentSlide) => { // [!code --]
  setSelectedIndex(currentSlide); // [!code --]
}); // [!code --]

carousel.addEventListener("scrollsnapchange", (event) => { // [!code ++]
  setSelectedIndex(event.detail.index); // [!code ++]
}); // [!code ++]

Or use IntersectionObserver for wider browser support

const slides = Array.from(carousel.children); // [!code ++]
const observer = new IntersectionObserver( // [!code ++]
  (entries) => { // [!code ++]
    const activeEntry = entries.find((entry) => entry.isIntersecting); // [!code ++]
    if (activeEntry) { // [!code ++]
      setSelectedIndex(slides.indexOf(activeEntry.target)); // [!code ++]
    } // [!code ++]
  }, // [!code ++]
  { root: carousel, threshold: 0.5 }, // [!code ++]
); // [!code ++]
slides.forEach((slide) => observer.observe(slide)); // [!code ++]
```

## Features

Slick features usually become either small Blossom wrappers or native platform features.

| Slick feature   | Blossom replacement                                    |
| --------------- | ------------------------------------------------------ |
| Arrows          | `<BlossomPrev>` and `<BlossomNext>` components.        |
| Dots            | `<BlossomDots>` with `data-blossom-slide` on slides.   |
| Autoplay        | A manual timer that scrolls the next slide into view.  |
| Fade            | CSS scroll-driven animations or intersection state.    |
| Lazy load       | Native `loading="lazy"` or framework image components. |
| Rows            | CSS grid.                                              |
| Syncing sliders | Shared selected state plus `scrollIntoView()`.         |

Rebuild Slick features deliberately. Native scrolling often replaces more of Slick than expected.

## Lifecycle

Slicks's and Blossom's lifecycle methods are similar.

::note{color="neutral" icon="i-lucide-lightbulb"}
Blossom initializes automatically when using framework components.
::

```ts
$(".carousel").slick("refresh"); // [!code --]
$(".carousel").slick("unslick"); // [!code --]
blossom.init(); // [!code ++]
blossom.destroy(); // [!code ++]
```

## Migration checklist

- Remove Slick packages and install the matching Blossom package.
- Import the stylesheet from your framework package once (for example `@blossom-carousel/vue/style.css`).
- Replace Slick markup and generated track assumptions with `<BlossomCarousel>` and direct slide children.
- Move slide sizing, gaps, snapping, center mode, and responsive behavior into CSS.
- Replace `slickPrev` and `slickNext` with `<BlossomPrev>` and `<BlossomNext>`.
- Replace `slickGoTo` with `scrollIntoView()` or native `scrollTo()`.
- Replace Slick events with browser observers or scroll snap events.
- Rebuild only the Slick features your carousel still needs.

## Next steps

- [Installation](https://www.blossom-carousel.com/docs/getting-started/installation) - Pick the package for your framework.
- [Snapping](https://www.blossom-carousel.com/docs/examples/basic/snap) - Configure scroll snap behavior with CSS.
- [Buttons](https://www.blossom-carousel.com/docs/examples/basic/buttons) - Add previous and next controls.
- [Dots](https://www.blossom-carousel.com/docs/examples/basic/dots) - Add dot markers with `<BlossomDots>`.
- [Repeat](https://www.blossom-carousel.com/docs/examples/experimental/repeat) - Explore an experimental repeating carousel pattern.


# Flickity

Flickity creates a carousel from cell elements, option objects, generated controls, selected-cell state, and a JavaScript instance.

Blossom keeps the carousel as a native scroll container. Layout, slide sizing, cell alignment, spacing, and responsive behavior belong in CSS, while Blossom adds dragging and small convenience methods.

## Migration mindset

When moving from Flickity to Blossom, migrate the carousel in three steps:

1. Replace Flickity initialization with a single `<BlossomCarousel>` root and direct children.
2. Move Flickity options such as `cellAlign`, `contain`, `wrapAround`, and `groupCells` into CSS or native scrolling.
3. Replace Flickity methods and events with Blossom methods, native scroll APIs, and browser observers.

::note{color="neutral" icon="i-lucide-lightbulb"}
Flickity migrations work best when you treat each cell as a normal scroll-snap child instead of a measured item in a carousel engine.
::

## Installation

Remove Flickity and install the matching Blossom package for your framework.

::code-group{sync="migration-code-style"}
```bash [Vue]
npm uninstall vue-flickity flickity
npm install @blossom-carousel/vue
```

```bash [React]
npm uninstall react-flickity-component flickity
npm install @blossom-carousel/react
```

```bash [Svelte]
npm uninstall flickity
npm install @blossom-carousel/svelte
```

```bash [Core]
npm uninstall flickity
npm install @blossom-carousel/core
```
::

Import the stylesheet from your framework package once in your app.

::code-group
```js [Vue]
import "@blossom-carousel/vue/style.css";
```

```js [React]
import "@blossom-carousel/react/style.css";
```

```js [Svelte]
import "@blossom-carousel/svelte/style.css";
```

```js [Core]
import "@blossom-carousel/core/style.css";
```

```js [Web]
import "@blossom-carousel/web/style.css";
```
::

## Component structure

Flickity initializes behavior on an element and treats its children as cells. Blossom keeps that direct-child model, but the root itself is the native scroll container.

::code-group{sync="migration-code-style"}
```vue [Vue]
<script setup lang="ts">
import Flickity from "vue-flickity"; // [!code --]
import "flickity/css/flickity.css"; // [!code --]
import { BlossomCarousel } from "@blossom-carousel/vue"; // [!code ++]
import "@blossom-carousel/vue/style.css"; // [!code ++]
</script>

<template>
  <Flickity :options="{ cellAlign: "left", contain: true }"> <!-- [!code --] -->
    <div class="carousel-cell">Slide 1</div> <!-- [!code --] -->
    <div class="carousel-cell">Slide 2</div> <!-- [!code --] -->
    <div class="carousel-cell">Slide 3</div> <!-- [!code --] -->
  </Flickity> <!-- [!code --] -->
  <BlossomCarousel class="carousel grid! grid-auto-cols grid-cols-[calc((100% - 3rem) / 4)] gap-4"> <!-- [!code ++] -->
    <div class="slide snap-start">Slide 1</div> <!-- [!code ++] -->
    <div class="slide snap-start">Slide 2</div> <!-- [!code ++] -->
    <div class="slide snap-start">Slide 3</div> <!-- [!code ++] -->
  </BlossomCarousel> <!-- [!code ++] -->
</template>
```

```tsx [React]
import Flickity from "react-flickity-component"; // [!code --]
import "flickity/css/flickity.css"; // [!code --]
import { BlossomCarousel } from "@blossom-carousel/react"; // [!code ++]
import "@blossom-carousel/react/style.css"; // [!code ++]

export function Carousel() {
  return (
    <Flickity options={{ cellAlign: "left", contain: true }}> {/* [!code --] */}
      <div className="carousel-cell">Slide 1</div> {/* [!code --] */}
      <div className="carousel-cell">Slide 2</div> {/* [!code --] */}
      <div className="carousel-cell">Slide 3</div> {/* [!code --] */}
    </Flickity> {/* [!code --] */}
    <BlossomCarousel className="carousel grid! grid-auto-cols grid-cols-[calc((100% - 3rem) / 4)] gap-4"> {/* [!code ++] */}
      <div className="slide snap-start">Slide 1</div> {/* [!code ++] */}
      <div className="slide snap-start">Slide 2</div> {/* [!code ++] */}
      <div className="slide snap-start">Slide 3</div> {/* [!code ++] */}
    </BlossomCarousel> {/* [!code ++] */}
  );
}
```

```svelte [Svelte]
<script>
  import { onMount } from "svelte"; // [!code --]
  import Flickity from "flickity"; // [!code --]
  import "flickity/css/flickity.css"; // [!code --]
  import { BlossomCarousel } from "@blossom-carousel/svelte"; // [!code ++]
  import "@blossom-carousel/svelte/style.css"; // [!code ++]

  let carousel; // [!code --]

  onMount(() => { // [!code --]
    const flickity = new Flickity(carousel, { cellAlign: "left", contain: true }); // [!code --]
    return () => flickity.destroy(); // [!code --]
  }); // [!code --]
</script>

<div class="carousel" bind:this={carousel}> <!-- [!code --] -->
  <div class="carousel-cell">Slide 1</div> <!-- [!code --] -->
  <div class="carousel-cell">Slide 2</div> <!-- [!code --] -->
  <div class="carousel-cell">Slide 3</div> <!-- [!code --] -->
</div> <!-- [!code --] -->
<BlossomCarousel class="carousel grid! grid-auto-cols grid-cols-[calc((100% - 3rem) / 4)] gap-4"> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 1</div> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 2</div> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 3</div> <!-- [!code ++] -->
</BlossomCarousel> <!-- [!code ++] -->
```

```html [Core]
<div class="carousel"> <!-- [!code --] -->
  <div class="carousel-cell">Slide 1</div> <!-- [!code --] -->
  <div class="carousel-cell">Slide 2</div> <!-- [!code --] -->
  <div class="carousel-cell">Slide 3</div> <!-- [!code --] -->
</div> <!-- [!code --] -->
<blossom-carousel class="carousel grid! grid-auto-cols grid-cols-[calc((100% - 3rem) / 4)] gap-4"> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 1</div> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 2</div> <!-- [!code ++] -->
  <div class="slide snap-start">Slide 3</div> <!-- [!code ++] -->
</blossom-carousel> <!-- [!code ++] -->
```
::

## Options

Flickity options describe how its engine measures and aligns cells. In Blossom, most of those choices become CSS and native scroll behavior.

| Flickity concept      | Blossom approach                                                                                                                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `cellAlign: "left"`   | Use `scroll-snap-align: start`.                                                                                                                                                                        |
| `cellAlign: "center"` | Use `scroll-snap-align: center`.                                                                                                                                                                       |
| `contain`             | Use native scroll bounds, padding, and `scroll-padding`.                                                                                                                                               |
| `groupCells`          | Create grouped slide elements or use native scrolling to target every nth slide.                                                                                                                       |
| `wrapAround`          | Prefer bounded native scrolling, or use the experimental repeat pattern when an infinite effect is required. See [Repeat example](https://www.blossom-carousel.com/docs/examples/experimental/repeat). |
| `freeScroll`          | Omit `scroll-snap-align` or use `scroll-snap-type: proximity`.                                                                                                                                         |
| `rightToLeft`         | Use `dir="rtl"` or CSS `direction: rtl`.                                                                                                                                                               |
| `adaptiveHeight`      | Let content define height, or update layout with `ResizeObserver`.                                                                                                                                     |
| `prevNextButtons`     | Use `<BlossomPrev>` and `<BlossomNext>`. See [Buttons example](https://www.blossom-carousel.com/docs/examples/basic/buttons).                                                                          |
| `pageDots`            | Use `<BlossomDots for="my-carousel">` and mark slides with `data-blossom-slide`. See [Dots example](https://www.blossom-carousel.com/docs/examples/basic/dots).                                        |

For example, this Flickity setup:

```js [Flickity]
const flkty = new Flickity(".carousel", {
  cellAlign: "center",
  contain: true,
  groupCells: true,
  wrapAround: false,
});
```

becomes CSS:

```css [Blossom]
.carousel {
  display: grid;
  grid-auto-flow: column;
  grid-auto-columns: 25%;
  gap: 1rem;
  scroll-snap-type: inline mandatory;
  scroll-padding-inline: 10%;
}

.slide {
  scroll-snap-align: center;
}
```

## Controls

Flickity controls call methods on the Flickity instance. Blossom provides `<BlossomPrev>`, `<BlossomNext>`, and `<BlossomDots>` components that link to the carousel through matching `id` and `for` props.

```ts
flkty.previous(); // [!code --]
flkty.next(); // [!code --]
```

```html
<BlossomCarousel id="gallery" class="carousel">
  <div data-blossom-slide class="slide">Slide 1</div>
  ...
</BlossomCarousel>

<div class="controls">
  <BlossomPrev for="gallery" />
  <BlossomNext for="gallery" />
</div>

<BlossomDots for="gallery" />
```

For direct slide navigation, use native scrolling on the target slide.

```ts
slides[index].scrollIntoView({
  behavior: "smooth",
  inline: "center",
  block: "nearest",
});
```

## API

Flickity commonly uses the `select` event and `selectedIndex` to track the active cell.

With Blossom, the carousel is a real scroll container, so use browser APIs such as `IntersectionObserver`, `scrollsnapchange`, or `scroll` events depending on the browser support you need.

```ts
flkty.on("select", () => { // [!code --]
  setSelectedIndex(flkty.selectedIndex); // [!code --]
}); // [!code --]

carousel.addEventListener("scrollsnapchange", (event) => { // [!code ++]
  setSelectedIndex(event.detail.index); // [!code ++]
}); // [!code ++]

Or use IntersectionObserver for wider browser support

const slides = Array.from(carousel.children); // [!code ++]
const observer = new IntersectionObserver( // [!code ++]
  (entries) => { // [!code ++]
    const activeEntry = entries.find((entry) => entry.isIntersecting); // [!code ++]
    if (activeEntry) { // [!code ++]
      setSelectedIndex(slides.indexOf(activeEntry.target)); // [!code ++]
    } // [!code ++]
  }, // [!code ++]
  { root: carousel, threshold: 0.5 }, // [!code ++]
); // [!code ++]
slides.forEach((slide) => observer.observe(slide)); // [!code ++]
```

## Features

Flickity features usually become either small Blossom wrappers or native platform features.

| Flickity feature        | Blossom replacement                                                              |
| ----------------------- | -------------------------------------------------------------------------------- |
| Previous / next buttons | `<BlossomPrev>` and `<BlossomNext>` components.                                  |
| Page dots               | `<BlossomDots>` with `data-blossom-slide` on slides.                             |
| Auto play               | A manual timer that scrolls the next slide into view.                            |
| Lazy load               | Native `loading="lazy"` and `content-visibility: auto`.                          |
| As nav for              | Shared selected state plus `scrollIntoView()`.                                   |
| Images loaded           | Native image loading events or `ResizeObserver` if layout depends on image size. |
| Fade                    | CSS scroll-driven animations or intersection state.                              |

Keep feature migrations small. Start from a working Blossom carousel, then add behavior back only if the product still needs it.

## Lifecycle

Flickity's and Blossom's lifecycle methods are similar.

::note{color="neutral" icon="i-lucide-lightbulb"}
Blossom initializes automatically when using framework components.
::

```ts
flkty.resize(); // [!code --]
flkty.destroy(); // [!code --]
blossom.init(); // [!code ++]
blossom.destroy(); // [!code ++]
```

## Migration checklist

- Remove Flickity packages and install the matching Blossom package.
- Import the stylesheet from your framework package once (for example `@blossom-carousel/vue/style.css`).
- Replace Flickity initialization with `<BlossomCarousel>` and direct slide children.
- Move cell sizing, alignment, gaps, snapping, direction, and breakpoints into CSS.
- Replace `previous()` and `next()` with `<BlossomPrev>` and `<BlossomNext>`.
- Replace `select(index)` with `scrollIntoView()` or native `scrollTo()`.
- Replace Flickity events with browser observers or scroll snap events.
- Rebuild only the Flickity features your carousel still needs.

## Next steps

- [Installation](https://www.blossom-carousel.com/docs/getting-started/installation) - Pick the package for your framework.
- [Snapping](https://www.blossom-carousel.com/docs/examples/basic/snap) - Configure scroll snap behavior with CSS.
- [Buttons](https://www.blossom-carousel.com/docs/examples/basic/buttons) - Add previous and next controls.
- [Dots](https://www.blossom-carousel.com/docs/examples/basic/dots) - Add dot markers with `<BlossomDots>`.
- [Repeat](https://www.blossom-carousel.com/docs/examples/experimental/repeat) - Explore an experimental repeating carousel pattern.


# Navigation controls with the Invoker Commands API

Blossom Carousel now ships first-class navigation controls through `<BlossomPrev>`, `<BlossomNext>`, and `<BlossomDots>` — with `<BlossomDot>` for fully custom dot buttons. These components work across the Vue, React, Svelte, and Web Components packages, and they can live anywhere in your layout.

:blog-navigation-controls

Link them to a carousel with a simple `id` / `for` pairing and Blossom handles the rest. No template ref, no layout constraints and no imperative API.

```html
<BlossomCarousel id="gallery" class="carousel">
  <div data-blossom-slide class="slide">Slide 01</div>
  <div data-blossom-slide class="slide">Slide 02</div>
  <div data-blossom-slide class="slide">Slide 03</div>
  ...
</BlossomCarousel>

<BlossomPrev for="gallery" />
<BlossomDots for="gallery" />
<BlossomNext for="gallery" />
```

Mark each slide with `data-blossom-slide` so dot navigation knows which elements to track. You choose how you want to build your slides markup—flat, nested or grouped—and you decide which elements you want to be tracked.

## How they work

Under the hood, each control is a native `<button type="button">` wired to the browser's **Invoker Commands API**:

- `commandfor` points at the carousel's `id`
- `command` names the action to perform

Blossom uses custom commands in the `--blossom-*` namespace:

| Control                | Command                  |
| ---------------------- | ------------------------ |
| BlossomPrev            | `--blossom-prev`         |
| BlossomNext            | `--blossom-next`         |
| BlossomDot (slide *n*) | `--blossom-goto-{index}` |

When you click a control, the browser dispatches a `command` event on the target carousel. Blossom listens for that event and scrolls the container using native `Element.scrollIntoView({ behavior: 'smooth', inline: … })`, with full awareness of scroll snap alignment, scroll padding, and RTL direction.

If no snap targets are found, it falls back to a proportional `scrollBy()`.

The controls and carousel stay decoupled and layout independent. As long as `for` matches the carousel's `id` it works.

## Why Invoker Commands

Blossom is built on a simple idea: &#x2A;*enhance native scrolling, don't replace it.** Navigation controls had to follow the same rules and for Blossom to feel like a native element it has to be able to exist on its own.

Most carousel libraries expose imperative APIs — grab a ref, call `.next()`, wire up click handlers in JavaScript or force a template ref around the carousel and controls to create a local scope. These patterns work, but it couples your controls to your component tree and to Blossom's runtime. Invoker Commands invert that: the button declares what it wants to do, the carousel responds.

The absense of an imperative API also means controls work even when Blossom's drag engine isn't loaded. On touch devices, where Blossom skips the drag bundle entirely, Blossom's navigation controls still scroll the carousel through native behavior.

Since Invoker Commands only reached Baseline in early 2026, Blossom still includes a lightweight fallback for browsers without native `commandForElement` support.

## What you don't have to think about

The navigation layer handles the details:

- **Disabled state** — prev/next buttons disable automatically at the first and last slide
- **Active dot tracking** — BlossomDots observes scroll position and sets `data-active` on the current dot
- **RTL** — scroll direction is respected when `direction: rtl` is set on the carousel
- **Scroll snap** — navigation finds snap-aligned pages and scrolls to the correct inline position

Default dots can be themed with CSS custom properties on `<BlossomDots>` or any ancestor. For fully custom dot UI, provide a default slot and render `<BlossomDot>` for each slide — Blossom wires up the button and navigation for you.

```css
/* defaults */
{
  --blossom-dot-size: 0.625rem;
  --blossom-dot-radius: 50%;
  --blossom-dot-color: currentColor;
  --blossom-dot-opacity: 0.35;
  --blossom-dot-hover-opacity: 0.6;
  --blossom-dot-active-opacity: 1;
}
```

```html
<!-- using a slotted svg icon -->
<BlossomPrev for="gallery">
  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor">
    <path d="m12 19-7-7 7-7" />
    <path d="M19 12H5" />
  </svg>
</BlossomPrev>

<!-- Thumbnail navigation with BlossomDot -->
<BlossomDots for="gallery" v-slot="{ index, active }">
  <BlossomDot :data-active="active" :aria-label="`Photo ${index + 1}`">
    <img :src="thumbnails[index]" />
  </BlossomDot>
</BlossomDots>
```

---

**Explore further:**

- [Buttons example](https://www.blossom-carousel.com/docs/examples/basic/buttons) — prev/next controls with CSS and Tailwind
- [Dots example](https://www.blossom-carousel.com/docs/examples/basic/dots) — dot navigation and custom dot UI
- [Thumbnails example](https://www.blossom-carousel.com/docs/examples/basic/thumbnails) — thumbnail navigation with `<BlossomDot>`


# How to make a flipbook-style carousel with Blossom

A flipbook carousel looks like it needs a custom animation engine. It doesn't. The effect in our [flipbook example](https://www.blossom-carousel.com/docs/examples/advanced/flipbook) is built from three web platform features: **scroll snap*&#x2A;, &#x2A;*`position: sticky`** and **scroll-driven animations**. Blossom provides the native scrolling and a small overscroll hook for the page-turn at the edges.

## What we're building

:blog-flipbook

::supports-view-timeline-support
  :::caution
  View-timeline is not yet supported in this browser. Check browser compatibility at 

  [caniuse.com](https://caniuse.com/?search=scroll-snap-change){rel=""nofollow""}
  :::
::

::supports-view-timeline-safari-support
  :::caution
  Safari's 

  `view-timeline`

   implementation does not yet account for sticky offsets when calculating 

  `animation-range: contain`

  , so scroll-driven animations in this example appear incorrect. See 

  [WebKit bug 288913](https://bugs.webkit.org/show_bug.cgi?id=288913){rel=""nofollow""}

  .
  :::
::

As you scroll (or drag) through the carousel, cards fan out in 3D space, settle face-on in the center, then peel away behind the stack. Pull past the first or last card and the whole stack bends like you're forcing a page turn.

Blossom's role here is small but important: it gives you a real horizontal scroll container with optional drag on desktop, and an `overscroll` event when the user pulls beyond the scroll range. Everything else is CSS.

Let's build it up step by step. Each step below has a live demo, so you can see exactly what each layer adds.

## Step 1: Set up the scroll container

Start with a horizontal grid where each slide takes the full viewport width of the carousel, and scroll snap locks to each page:

```css
.carousel {
  --card-width: 12rem;

  display: grid;
  grid-auto-flow: column;
  grid-auto-columns: 100%;
  scroll-snap-type: x mandatory;

  /* Show one card with neighbors peeking on each side */
  width: calc(var(--card-width) * 3);
  padding-inline: var(--card-width);
  box-sizing: border-box;
}

.slide {
  width: var(--card-width);
  aspect-ratio: 3 / 4;
}
```

```html
<BlossomCarousel class="carousel">
  <div class="slide">
    <div class="card"></div>
  </div>
  <div class="slide">
    <div class="card"></div>
  </div>
  <div class="slide">
    <div class="card"></div>
  </div>
  <!-- ... -->
</BlossomCarousel>
```

:blog-flipbook-step1

Nothing fancy yet, just a snapping horizontal scroller. Each column is as wide as the carousel itself, which is why you see so much space between the cards. That will make sense in the next step.

## Step 2: Sticky stacking

Now make each slide `position: sticky` with negative inset offsets. This keeps every card pinned to the same visual slot as you scroll, so cards **stack on top of each other** instead of sliding side by side like a normal carousel:

```css
.slide {
  position: sticky;
  left: calc(var(--card-width) * -1);
  right: calc(var(--card-width) * -1);
}
```

:blog-flipbook-step2

The grid still advances one full column per snap point, but sticky positioning pulls each card back into the center frame. Every card now passes through the same region as you scroll, which is exactly the setup we need to animate them in 3D.

## Step 3: Scroll-driven animations

Attach a **view timeline** to each slide so its animation progress tracks how far that slide has traveled through the scrollport:

```css
.slide {
  view-timeline: --cards inline;
  animation: stack-cards linear both;
  animation-timeline: --cards;
  animation-range: contain;
}
```

The named timeline `--cards` is scoped to each slide's journey through the carousel, and `animation-range: contain` runs the animation for the full time the slide is visible in the scrollport.

This first animation only manages **stacking order**, in other words which card sits on top as it moves through the center:

```css
@keyframes stack-cards {
  0% {
    z-index: calc(sibling-count() - sibling-index());
  }
  50% {
    z-index: 1000;
  }
  100% {
    z-index: sibling-index();
  }
}
```

`sibling-index()` is a CSS function that returns each slide's index among its siblings. Cards entering from the left start on top, the active card peaks at `z-index: 1000` in the middle, and cards exiting sink behind the stack.

:blog-flipbook-step3

It still looks static, but scroll slowly and watch the cards swap places. The stacking order is now correct, we just need the cards to actually move.

## Step 4: 3D card rotation

The visible flip happens on an inner `.card` element. Separating the sticky wrapper from the rotating card keeps the scroll and transform concerns isolated:

```css
.slide {
  perspective: 1200px;

  & .card {
    width: 100%;
    height: 100%;
    transform-style: preserve-3d;

    animation: rotate-cards linear both;
    animation-timeline: --cards;
    animation-range: contain -50% contain 150%;
  }
}
```

The wider animation range (`contain -50% contain 150%`) starts the rotation slightly before the slide enters and finishes slightly after it leaves, so the motion feels continuous rather than clipped.

The keyframes move each card through a 3D arc: offset to the side, rotated on the Y axis, flat in the center, then mirrored on the way out:

```css
@keyframes rotate-cards {
  0% {
    transform: translateX(-100%) translateZ(-200px) rotateY(-35deg);
  }
  25% {
    transform: translateX(-80%) translateZ(-100px) rotateY(-35deg);
  }
  37.5% {
    transform: translateX(-15%) translateZ(-100px) rotateY(-20deg);
  }
  50% {
    transform: translateX(0%) translateZ(0px) rotateY(0deg);
  }
  62.5% {
    transform: translateX(15%) translateZ(-100px) rotateY(20deg);
  }
  75% {
    transform: translateX(80%) translateZ(-100px) rotateY(35deg);
  }
  100% {
    transform: translateX(100%) translateZ(-200px) rotateY(35deg);
  }
}
```

:blog-flipbook-step4

There's the flipbook. Feel free to tweak the translate and rotate values to change how dramatic the fan feels. The symmetry around the 50% keyframe keeps the motion balanced in both scroll directions.

## Step 5: Overscroll page turn

Scroll-driven animations handle everything within the scroll range. For the rubber-band **page turn** when the user drags past the first or last card, listen to Blossom's `overscroll` event:

```js
function handleOverscroll(event: CustomEvent) {
  event.preventDefault();
  const overscroll = event.detail.left;

  Array.from(event.target.children).forEach((child) => {
    const translate = `translateX(${overscroll * 0.5}px)`;
    const rotate = `rotateY(${(overscroll / event.target.clientWidth) * -90}deg)`;
    child.style.transform = `${translate} ${rotate}`;
  });
}

carousel.addEventListener('overscroll', handleOverscroll);
```

`event.detail.left` is the horizontal overscroll distance in pixels, positive when pulling right and negative when pulling left. We apply it directly as a transform on each slide. The `.prevent` modifier tells Blossom to skip its default rubber-band effect so our custom one takes over.

:blog-flipbook

Drag past the first or last card to see it. Note that this only runs when the drag engine is active (desktop with a fine pointer). Touch users still get native scroll at the edges, which is usually enough.

## Putting it together

::code-group{sync="migration-code-style"}
```vue [Vue]
<script setup>
function handleOverscroll(event: CustomEvent) {
  const overscroll = event.detail.left;

  Array.from(event.target.children).forEach((child) => {
    const translate = `translateX(${overscroll * 0.5}px)`;
    const rotate = `rotateY(${(overscroll / event.target.clientWidth) * -90}deg)`;
    child.style.transform = `${translate} ${rotate}`;
  });
}
</script>

<template>
  <BlossomCarousel class="carousel" @overscroll.prevent="handleOverscroll">
    <div v-for="i in 10" :key="i" class="slide">
      <div class="card">{{ i }}</div>
    </div>
  </BlossomCarousel>
</template>

<style scoped>
.carousel {
  --card-width: 12rem;
}

.slide {
  view-timeline: --cards inline;
  animation: stack-cards linear both;
  animation-timeline: --cards;
  animation-range: contain;

  & .card {
    animation: rotate-cards linear both;
    animation-timeline: --cards;
    animation-range: contain -50% contain 150%;
  }
}

@keyframes stack-cards {
  0% {
    z-index: calc(sibling-count() - sibling-index());
  }
  50% {
    z-index: 1000;
  }
  100% {
    z-index: sibling-index();
  }
}

@keyframes rotate-cards {
  0% {
    transform: translateX(-100%) translateZ(-200px) rotateY(-35deg);
  }
  25% {
    transform: translateX(-80%) translateZ(-100px) rotateY(-35deg);
  }
  37.5% {
    transform: translateX(-15%) translateZ(-100px) rotateY(-20deg);
  }
  50% {
    transform: translateX(0%) translateZ(0px) rotateY(0deg);
  }
  62.5% {
    transform: translateX(15%) translateZ(-100px) rotateY(20deg);
  }
  75% {
    transform: translateX(80%) translateZ(-100px) rotateY(35deg);
  }
  100% {
    transform: translateX(100%) translateZ(-200px) rotateY(35deg);
  }
}
</style>
```

```tsx [React]
function handleOverscroll(event: CustomEvent<{ left: number }>) {
  const overscroll = event.detail.left;

  Array.from(event.target.children).forEach((child) => {
    const translate = `translateX(${overscroll * 0.5}px)`;
    const rotate = `rotateY(${(overscroll / event.target.clientWidth) * -90}deg)`;
    child.style.transform = `${translate} ${rotate}`;
  });
}

return (
  <BlossomCarousel
    ref={carousel}
    className="carousel"
    onOverscroll={(event) =>
      handleOverscroll(event as CustomEvent<{ left: number }>)
    }
  >
    {Array.from({ length: 10 }, (_, index) => (
      <div key={index} className="slide">
        <div className="card">{index + 1}</div>
      </div>
    ))}
  </BlossomCarousel>
);

<style>
.carousel {
  --card-width: 12rem;
}

.slide {
  view-timeline: --cards inline;
  animation: stack-cards linear both;
  animation-timeline: --cards;
  animation-range: contain;

  & .card {
    animation: rotate-cards linear both;
    animation-timeline: --cards;
    animation-range: contain -50% contain 150%;
  }
}

@keyframes stack-cards {
  0% {
    z-index: calc(sibling-count() - sibling-index());
  }
  50% {
    z-index: 1000;
  }
  100% {
    z-index: sibling-index();
  }
}

@keyframes rotate-cards {
  0% {
    transform: translateX(-100%) translateZ(-200px) rotateY(-35deg);
  }
  25% {
    transform: translateX(-80%) translateZ(-100px) rotateY(-35deg);
  }
  37.5% {
    transform: translateX(-15%) translateZ(-100px) rotateY(-20deg);
  }
  50% {
    transform: translateX(0%) translateZ(0px) rotateY(0deg);
  }
  62.5% {
    transform: translateX(15%) translateZ(-100px) rotateY(20deg);
  }
  75% {
    transform: translateX(80%) translateZ(-100px) rotateY(35deg);
  }
  100% {
    transform: translateX(100%) translateZ(-200px) rotateY(35deg);
  }
}
</style>
```

```svelte [Svelte]
<script>
  function handleOverscroll(event) {
    event.preventDefault();
    const overscroll = event.detail.left;

    Array.from(event.target.children).forEach((child) => {
      const translate = `translateX(${overscroll * 0.5}px)`;
      const rotate = `rotateY(${(overscroll / event.target.clientWidth) * -90}deg)`;
      child.style.transform = `${translate} ${rotate}`;
    });
  }

  const slides = Array.from({ length: 10 }, (_, index) => index + 1);
</script>

<BlossomCarousel class="carousel" onoverscroll={handleOverscroll}>
  {#each slides as slide (slide)}
    <div class="slide">
      <div class="card">{slide}</div>
    </div>
  {/each}
</BlossomCarousel>

<style>
.carousel {
  --card-width: 12rem;
}

.slide {
  view-timeline: --cards inline;
  animation: stack-cards linear both;
  animation-timeline: --cards;
  animation-range: contain;

  & .card {
    animation: rotate-cards linear both;
    animation-timeline: --cards;
    animation-range: contain -50% contain 150%;
  }
}

@keyframes stack-cards {
  0% {
    z-index: calc(sibling-count() - sibling-index());
  }
  50% {
    z-index: 1000;
  }
  100% {
    z-index: sibling-index();
  }
}

@keyframes rotate-cards {
  0% {
    transform: translateX(-100%) translateZ(-200px) rotateY(-35deg);
  }
  25% {
    transform: translateX(-80%) translateZ(-100px) rotateY(-35deg);
  }
  37.5% {
    transform: translateX(-15%) translateZ(-100px) rotateY(-20deg);
  }
  50% {
    transform: translateX(0%) translateZ(0px) rotateY(0deg);
  }
  62.5% {
    transform: translateX(15%) translateZ(-100px) rotateY(20deg);
  }
  75% {
    transform: translateX(80%) translateZ(-100px) rotateY(35deg);
  }
  100% {
    transform: translateX(100%) translateZ(-200px) rotateY(35deg);
  }
}
</style>
```

```html [Web]
<blossom-carousel class="carousel">
  <div class="slide">
    <div class="card">1</div>
  </div>
  <div class="slide">
    <div class="card">2</div>
  </div>
  <div class="slide">
    <div class="card">3</div>
  </div>
  <!-- ... -->
</blossom-carousel>

<script type="module">
  import "@blossom-carousel/web";

  const carousel = document.querySelector(".carousel");

  carousel.addEventListener("overscroll", (event) => {
    event.preventDefault();
    const overscroll = event.detail.left;

    Array.from(carousel.children).forEach((child) => {
      const translate = `translateX(${overscroll * 0.5}px)`;
      const rotate = `rotateY(${(overscroll / carousel.clientWidth) * -90}deg)`;
      child.style.transform = `${translate} ${rotate}`;
    });
  });
</script>

<style>
  .carousel {
    --card-width: 12rem;
  }

  .slide {
    view-timeline: --cards inline;
    animation: stack-cards linear both;
    animation-timeline: --cards;
    animation-range: contain;

    & .card {
      animation: rotate-cards linear both;
      animation-timeline: --cards;
      animation-range: contain -50% contain 150%;
    }
  }

  @keyframes stack-cards {
    0% {
      z-index: calc(sibling-count() - sibling-index());
    }
    50% {
      z-index: 1000;
    }
    100% {
      z-index: sibling-index();
    }
  }

  @keyframes rotate-cards {
    0% {
      transform: translateX(-100%) translateZ(-200px) rotateY(-35deg);
    }
    25% {
      transform: translateX(-80%) translateZ(-100px) rotateY(-35deg);
    }
    37.5% {
      transform: translateX(-15%) translateZ(-100px) rotateY(-20deg);
    }
    50% {
      transform: translateX(0%) translateZ(0px) rotateY(0deg);
    }
    62.5% {
      transform: translateX(15%) translateZ(-100px) rotateY(20deg);
    }
    75% {
      transform: translateX(80%) translateZ(-100px) rotateY(35deg);
    }
    100% {
      transform: translateX(100%) translateZ(-200px) rotateY(35deg);
    }
  }
</style>
```
::

All of the layout and animation logic lives in CSS. Blossom doesn't know it's a flipbook, it just scrolls and allows it to be dragged.

---

## Browser support

Scroll-driven animations with `view-timeline` require a modern browser. Check [caniuse](https://caniuse.com/?search=view-timeline){rel="&#x22;nofollow&#x22;"} for current support.

Safari's `view-timeline` implementation does not yet account for sticky offsets when calculating `animation-range: contain`, so the animation timing may look off in Safari until [WebKit bug 288913](https://bugs.webkit.org/show_bug.cgi?id=288913){rel="&#x22;nofollow&#x22;"} is resolved.

## Explore further

- [Flipbook example](https://www.blossom-carousel.com/docs/examples/advanced/flipbook) has the full source with CSS and Tailwind variants
- [Cover flow example](https://www.blossom-carousel.com/docs/examples/advanced/cover-flow) is another scroll-driven 3D pattern
- [Overscroll API](https://www.blossom-carousel.com/docs/framework-guides/vue-nuxt#overscroll-api) documents what `event.detail` exposes


# Introducing Blossom Carousel

Carousels have become a powerful and popular choice among the many ways to structure content hierarchy. They are one of the main means to create a spatial form of progressive disclosure by collapsing vertical real estate while inviting horizontal exploration, and their scrolling behavior makes them stand out especially on touch devices where swiping is such a natural gesture.

A scroll container works naturally with touch, but dragging with a mouse or trackpad is still something developers need to build themselves. Historically, carousel libraries solved this by taking over completely: replacing the browser's scrolling model with their own JavaScript-powered implementation.

That made sense when the platform lacked the primitives we have today.

But the web has changed.

## The current state of carousels

A carousel is, at its core, simply a horizontal scroll container. Browsers know exceptionally well how to handle scrolling with smooth momentum, rubber-banding, keyboard navigation, touch handling and more. All of it ships for free inside the browser.

So it's strange that almost every carousel library throws all of that away. To make slides draggable, they stop scrolling entirely and slide a track around with CSS transforms instead.

Eventhough scrolling is the first casualty, the few libraries that try to win it back bolt scrolling on after the fact by intercepting the wheel, second-guessing every flick and nudge the browser would have handled for free. Either way you pay the same tax: motion that feels just slightly off, layout that fights the platform, and a bundle that grows with every edge case the browser already solved. And once scrolling is simulated, all its native capabilities are lost.

On top of that, because on touch devices dragging and scrolling is the same gesture many developers started rolling 2 different carousel solutions, one for touch and one for pointer devices.

The result is a strange split and we ended up with two different carousel implementations where one should be enough.

## Introducing Blossom

Blossom is a carousel built on a real scroll container. Your slides are real markup, your layout is real CSS, and the scroll position is the real, native source of truth. On top of that, Blossom adds one thing: a lightweight, physics-based drag engine for pointer devices that hands off seamlessly to native scrolling.

Here it is. Drag it with a mouse, flick it on a trackpad, swipe it on a phone. Same component, works everywhere.

:blog-simple

Because Blossom is built on a real scroll container, the browser's capabilities remain available.

That means features like these work naturally:

- `scroll-snap` controls slide alignment
- `position: sticky` creates layered layouts
- scroll-driven animations respond to real movement
- scroll-state queries can react to scroll position

Blossom does not introduce another abstraction for these things. It lets the platform continue doing what it already does best.

Your CSS describes the experience. Blossom simply makes the interaction complete.

| Feature                      | Blossom Carousel | Traditional Carousel Libraries |
| ---------------------------- | ---------------- | ------------------------------ |
| Draggable                    | ✅ Yes            | ✅ Yes                          |
| Scrollable                   | ✅ Yes            | ❌ No                           |
| Navigation controls          | ✅ Yes            | ✅ Yes                          |
| Cyclical scrolling           | ⚠️ Experimental  | ✅ Yes                          |
| Position sticky              | ✅ Yes            | ❌ No                           |
| CSS Scroll-driven animations | ✅ Yes            | ❌ No                           |
| Scroll-state queries         | ✅ Yes            | ❌ No                           |
| Scroll-snap events           | ✅ Yes            | ❌ No                           |
| Scroll event listeners       | ✅ Yes            | ❌ No                           |

## Built for the future of the web

The direction of the platform is moving toward more native carousel capabilities.

Browser vendors are already exploring ways to bring common carousel features directly into CSS and HTML, including native controls and more advanced scrolling behavior.

Blossom is designed around that same direction. Rather than fighting the platform, it follows it.
The future of carousels is not more JavaScript controlling more pixels. It is better primitives, composed together.

## Get started

Blossom ships as first-class components for React, Vue, Svelte, and Web Components, all sharing one framework-agnostic core. Pick the package that matches your stack:

::code-group{sync="migration-code-style"}
```bash [Vue]
npm install @blossom-carousel/vue
```

```bash [React]
npm install @blossom-carousel/react
```

```bash [Svelte]
npm install @blossom-carousel/svelte
```

```bash [Web]
npm install @blossom-carousel/web
```

```bash [Core]
npm install @blossom-carousel/core
```
::

Install Blossom for your framework, copy an example or install the [Agent Skills](https://www.blossom-carousel.com/docs/ai/agent-skills) to get started.

::code-block
```bash [Terminal]
npx skills add https://www.blossom-carousel.com
```

- [Installation](https://www.blossom-carousel.com/docs/getting-started/installation) — add Blossom to your project in one command.
- [Examples](https://www.blossom-carousel.com/docs/examples/basic/simple) — from a simple slider to cover flow, sticky stacks, and flipbooks.
::