blossom-carousel-react
Builds carousels with @blossom-carousel/react in React and Next.js, covering BlossomCarousel setup, CSS scroll-snap layouts, BlossomPrev/BlossomNext/BlossomDots/BlossomDot controls, ref methods (prev, next, goTo), useBlossomNavigation for custom controls, and command and overscroll events. Use when a React or Next.js project imports @blossom-carousel/react or renders <BlossomCarousel>, or when the user wants a Blossom carousel, slider, or gallery in React or Next.js.
How do I install this agent skill?
npx skills add https://blossom-carousel.com --skill blossom-carousel-reactIs this agent skill safe to install?
No partner audit is available yet. Read the source before installing.
What does this agent skill do?
Blossom Carousel for React and Next.js
<BlossomCarousel> renders a native horizontal scroll container. Layout, slide sizes, gaps, and snapping are plain CSS. Blossom adds mouse dragging with momentum and rubber-banding, and only downloads its drag engine on devices with a fine pointer. Touch devices keep native scrolling.
For migrations from Embla, Swiper, Splide, Slick, or Flickity, use the blossom-carousel-migration skill first.
Setup
npm install @blossom-carousel/react
Import the stylesheet once from the app entry or root layout (app/layout.tsx for the Next.js App Router, pages/_app.tsx for the Pages Router):
import "@blossom-carousel/react/style.css";
Then use the component wherever the carousel renders. The package doesn't ship a "use client" directive, so in the Next.js App Router, any file that renders Blossom components must start with "use client":
"use client";
import { BlossomCarousel } from "@blossom-carousel/react";
export function FeaturedCarousel({ items }) {
return (
<BlossomCarousel className="carousel">
{items.map((item) => (
<div key={item.id} className="slide">
{item.title}
</div>
))}
</BlossomCarousel>
);
}
Layout
Style the carousel root and slides with regular CSS. Each direct child is a slide.
.carousel {
display: grid;
grid-auto-flow: column;
grid-auto-columns: 200px;
gap: 1rem;
scroll-snap-type: inline mandatory; /* optional: snapping */
}
.slide {
scroll-snap-align: center;
}
Blossom's default styles are wrapped in @layer blossom-carousel, so normal CSS, CSS Modules, and Tailwind utilities override them without !important. Use Tailwind classes only if the project already uses Tailwind.
Props
| Prop | Type | Default | Purpose |
|---|---|---|---|
as | ElementType | "div" | Root element. Use as="ul" with <li> slides for list semantics. |
load | "conditional" | "always" | "conditional" | conditional loads the drag engine only when (hover: hover) and (pointer: fine) matches. |
repeat | boolean | false | Experimental looping mode. |
Other HTML attributes such as id, className, and aria-* are passed to the root element.
Navigation controls
Give the carousel an id, point each control's for prop at it, and mark slides with data-blossom-slide:
import { BlossomCarousel, BlossomPrev, BlossomNext, BlossomDots } from "@blossom-carousel/react";
<>
<BlossomCarousel id="gallery" className="carousel">
{items.map((item) => (
<div key={item.id} data-blossom-slide className="slide">
{item.title}
</div>
))}
</BlossomCarousel>
<BlossomPrev for="gallery" />
<BlossomDots for="gallery" />
<BlossomNext for="gallery" />
</>
- Controls are native buttons wired through the Invoker Commands API (with a built-in fallback). They need no ref and work on touch devices where the drag engine isn't loaded.
BlossomPrevandBlossomNextmove to the adjacent snap point, or page by about 85% of the viewport when nothing snaps. They disable themselves at the edges and default to the labels "Previous slide" and "Next slide". Pass a more specificaria-label, such as "Next products", when that's clearer.- Pass children to replace the default
‹and›icons:<BlossomNext for="gallery"><ArrowRight /></BlossomNext>. behavior="instant"orbehavior="auto"changes the scroll animation (defaultsmooth). OnBlossomDotsit applies to every dot, and aBlossomDotcan override it.
Theme the default dots with CSS custom properties on the dots or any ancestor:
.my-dots {
--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;
}
For fully custom dots, such as thumbnails, pass a render function and return a <BlossomDot>. It renders the <button> with navigation and ARIA attributes already set:
<BlossomDots for="gallery">
{({ index, active }) => (
<BlossomDot className="thumb" data-active={active} aria-label={`Show ${items[index].title}`}>
<img src={items[index].thumb} alt="" />
</BlossomDot>
)}
</BlossomDots>
Methods
Pass a ref to get a BlossomCarouselHandle with prev(options?), next(options?), goTo(index, options?), and element, which is the root element. goTo takes a zero-based index into the data-blossom-slide elements. options.behavior is "smooth" (default), "instant", or "auto". These methods use native scrolling, so they work on touch devices too.
import { useRef } from "react";
import { BlossomCarousel, type BlossomCarouselHandle } from "@blossom-carousel/react";
export function Gallery() {
const carousel = useRef<BlossomCarouselHandle>(null);
return (
<>
<BlossomCarousel ref={carousel} id="gallery">
{Array.from({ length: 12 }, (_, i) => (
<div key={i} data-blossom-slide>
Slide {i + 1}
</div>
))}
</BlossomCarousel>
<button type="button" onClick={() => carousel.current?.goTo(0, { behavior: "instant" })}>
Back to start
</button>
</>
);
}
Commands are registered in a layout effect, so a parent's useLayoutEffect can call goTo(i, { behavior: "instant" }) to set the starting slide before first paint.
Custom controls with useBlossomNavigation
useBlossomNavigation(id) returns { activeIndex, count, canPrev, canNext }. It's the same state the built-in controls use, and it only re-renders when a value changes. activeIndex is -1 until the carousel has been measured.
import { useRef } from "react";
import {
BlossomCarousel,
useBlossomNavigation,
type BlossomCarouselHandle,
} from "@blossom-carousel/react";
export function Gallery() {
const carousel = useRef<BlossomCarouselHandle>(null);
const { activeIndex, count, canPrev, canNext } = useBlossomNavigation("gallery");
return (
<>
<BlossomCarousel ref={carousel} id="gallery">
{/* slides with data-blossom-slide */}
</BlossomCarousel>
<button type="button" disabled={!canPrev} onClick={() => carousel.current?.prev()}>
Previous
</button>
<span>
{activeIndex + 1} / {count}
</span>
<button type="button" disabled={!canNext} onClick={() => carousel.current?.next()}>
Next
</button>
</>
);
}
Events
Pass onOverscroll and onCommand as props. BlossomCarousel attaches them with addEventListener and always calls the latest handler, so inline functions are fine:
import {
BlossomCarousel,
type BlossomCommandEvent,
type BlossomOverscrollEvent,
} from "@blossom-carousel/react";
export function Gallery() {
const onOverscroll = (event: BlossomOverscrollEvent) => {
event.preventDefault(); // replace the default rubber-band transform
const offset = event.detail.left;
for (const slide of (event.currentTarget as HTMLElement).children) {
(slide as HTMLElement).style.transform = `scale(${1 - Math.abs(offset) * 0.001})`;
}
};
const onCommand = (event: BlossomCommandEvent) => {
const command = event.command ?? event.detail?.command;
// "--blossom-prev" | "--blossom-next" | "--blossom-goto-{index}"
};
return (
<BlossomCarousel onOverscroll={onOverscroll} onCommand={onCommand}>
{/* slides */}
</BlossomCarousel>
);
}
These props require @blossom-carousel/react 1.8.0 or later. Check the installed version; on older versions React drops them with an "Unknown event handler property" warning, so attach listeners to ref.current.element in a useEffect instead.
commandfires when a control or method navigates. Dragging and free scrolling don't fire it.overscrollfires while the drag engine rubber-bands past an edge.detail.leftis the offset in pixels.- To react to the active slide, use
useBlossomNavigation().activeIndex. The drag engine also emitsscrollend,scrollsnapchange, andscrollsnapchanging, matching the native events. Attach those withaddEventListenertoo.
Gotchas
onOverscrollandonCommandonly work from 1.8.0. Other non-React events such asscrollsnapchangestill needaddEventListeneronref.current.element.- The ref is a
BlossomCarouselHandle, not an element. Useref.current.elementfor the DOM node. - In the Next.js App Router, files that render Blossom components need
"use client", even when the carousel has no interactivity of its own. - Dots and
goTocount only elements withdata-blossom-slide(at any depth). Without the attribute, there are no dots andgoTodoes nothing. Prev and next work without it. - The
forprop must match the carouselidexactly. With several carousels on a page, generate ids withuseId(). - Render
<BlossomDots>after its<BlossomCarousel>in the JSX. The carousel registers its slide count while rendering, so dots rendered earlier start empty during SSR and only fill in after hydration. <BlossomDot>only works inside the<BlossomDots>render function.- Dot styling uses
[data-blossom-dots],[data-blossom-dot],[data-blossom-dot-marker], and[aria-current="true"]. The old.blossom-dotsand.blossom-dotclasses no longer exist. - Keep
overflow-xon the root asauto(the default).overflow: hiddendisables dragging. - The drag engine reads
scroll-snap-typeonce, when it initializes, so a snap type that changes in a media query is ignored for mouse dragging. Keepscroll-snap-typeconstant and varyscroll-snap-alignon the slides instead, or re-mount the carousel with a newkeywhen the snap type has to change. - Overscroll events come from the drag engine, so with the default
load="conditional"they never fire on touch devices. Treat custom overscroll effects as a mouse enhancement. - If slides change after mount, Blossom remeasures automatically. Don't change the carousel's
keyto force a refresh. @blossom-carousel/react1.7.0 shipped development-only JSX and fails with production React. Use 1.7.1 or later.
Accessibility baseline
Wrap the carousel in a labelled <section>, use as="ul" with <li> slides for lists of items, and include BlossomPrev/BlossomNext or dots, because dragging alone does not meet WCAG 2.5.7. Give controls names that describe what they show, for example "Next products".
Further docs
Fetch these only when the task needs them:
- Layout recipes (cover flow, stacks, thumbnails, sticky, RTL, masonry): read the index at https://www.blossom-carousel.com/raw/docs/examples.md, then fetch the matching example. Examples use Vue-style
<BlossomCarousel>markup with CSS and Tailwind variants. ConvertclasstoclassName, addkeyprops, and move event bindings into effects. - Accessibility questions (ARIA, keyboard, focus, reduced motion, auto-rotation, screen readers, WCAG): https://www.blossom-carousel.com/raw/docs/a11y/accessibility-guide.md
- Full docs index: https://www.blossom-carousel.com/llms.txt
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/blossom-carousel.com/blossom-carousel-react">View blossom-carousel-react on skillZs</a>