Migration Guides

Swiper

Migrate from Swiper to Blossom Carousel by replacing Swiper modules, wrappers, and configuration with native scrolling and CSS.

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:

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

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.

npm uninstall swiper
npm install @blossom-carousel/vue

npm uninstall swiper
npm install @blossom-carousel/react

npm uninstall swiper
npm install @blossom-carousel/svelte

npm uninstall swiper
npm install @blossom-carousel/core

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

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

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

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

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

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.

<script setup lang="ts">
import { Swiper, SwiperSlide } from "swiper/vue";import "swiper/css";import { BlossomCarousel } from "@blossom-carousel/vue";import "@blossom-carousel/vue/style.css";</script>

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

import { Swiper, SwiperSlide } from "swiper/react";import "swiper/css";import { BlossomCarousel } from "@blossom-carousel/react";import "@blossom-carousel/react/style.css";
export function Carousel() {
  return (
    <Swiper slidesPerView={1.25} spaceBetween={16}>      <SwiperSlide>Slide 1</SwiperSlide>      <SwiperSlide>Slide 2</SwiperSlide>      <SwiperSlide>Slide 3</SwiperSlide>    </Swiper>    <BlossomCarousel className="carousel grid! grid-auto-cols grid-cols-[25%] gap-4">      <div className="slide snap-start">Slide 1</div>      <div className="slide snap-start">Slide 2</div>      <div className="slide snap-start">Slide 3</div>    </BlossomCarousel>  );
}

<script>
  import { Swiper, SwiperSlide } from "swiper/svelte";  import "swiper/css";  import { BlossomCarousel } from "@blossom-carousel/svelte";  import "@blossom-carousel/svelte/style.css";</script>

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

<div class="swiper">  <div class="swiper-wrapper">    <div class="swiper-slide">Slide 1</div>    <div class="swiper-slide">Slide 2</div>    <div class="swiper-slide">Slide 3</div>  </div></div><div class="carousel grid! grid-auto-cols grid-cols-[25%] gap-4">  <div class="slide snap-start">Slide 1</div>  <div class="slide snap-start">Slide 2</div>  <div class="slide snap-start">Slide 3</div></div>
<script type="module">
  import Swiper from "swiper";  import "swiper/css";  import { Blossom } from "@blossom-carousel/core";  import "@blossom-carousel/core/style.css";
  const swiper = new Swiper(".swiper", {    slidesPerView: 1.25,    spaceBetween: 16,  });
  const carouselElement = document.querySelector(".carousel");  const blossom = Blossom(carouselElement);  blossom.init();</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.
`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:

Swiper

const swiperOptions = {
  slidesPerView: 1,
  spaceBetween: 16,
  centeredSlides: false,
  breakpoints: {
    768: { slidesPerView: 3, centeredSlides: true },
  },
};

becomes 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.

swiper.slidePrev();swiper.slideNext();

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

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.

swiper.on("slideChange", () => {  setSelectedIndex(swiper.activeIndex);});
carousel.addEventListener("scrollsnapchange", (event) => {  setSelectedIndex(event.detail.index);});
Or use IntersectionObserver for wider browser support

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

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.

Blossom initializes automatically when using framework components.

swiper.update();swiper.destroy();blossom.init();blossom.destroy();

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 - Pick the package for your framework.
Snapping - Configure scroll snap behavior with CSS.
Buttons - Add previous and next controls.
Dots - Add dot markers with <BlossomDots>.
Repeat - Explore an experimental repeating carousel pattern.

Embla

Migrate from Embla Carousel to Blossom Carousel by moving layout and behavior back to native scrolling and CSS.

Splide

Migrate from Splide to Blossom Carousel by replacing Splide tracks, lists, options, and events with native scrolling and CSS.