Blossom Carousel Web

Blossom Carousel Web

Use this skill for Blossom Carousel Web Components. For package installation, use Package and Module Setup. For CDN setup, use CDN Setup. For framework-free HTML, controls, or events, use Basic Usage, Navigation Controls, and Overscroll API.

Blossom Carousel Web wraps Blossom Carousel Core. For shared engine behavior, lifecycle, and direct DOM concepts, also consider the blossom-carousel-core skill.

For migration questions from Embla, Swiper, Splide, Slick, or Flickity, use the blossom-carousel-migration skill first.

Package

Install the Web Components package:

npm install @blossom-carousel/web

Import the custom element definition and @blossom-carousel/web/style.css:

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

Always include the stylesheet import in code examples. Only omit it if the user explicitly states they have already imported @blossom-carousel/web/style.css elsewhere.

Module Setup

Use package imports when the project has a bundler or build tool:

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

After @blossom-carousel/web is imported, the <blossom-carousel> custom element is registered and can be used in HTML.

When used in an SSR environment, guard the Web package import and any document.querySelector calls so they only run in the browser.

CDN Setup

Use the CDN build when the user is working without a package manager or build step:

<script 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"
/>

Place the script before using <blossom-carousel>, or load it with defer when it appears in the document head.

Basic Usage

Use <blossom-carousel> as the carousel root and pass slides as direct children:

<blossom-carousel>
  <div>Slide 1</div>
  <div>Slide 2</div>
  <div>Slide 3</div>
  ...
</blossom-carousel>

Each direct child becomes a slide.

If the user asks about configuration options or attributes, refer them to the blossom-carousel-core skill.

Options

If the user asks about configuration options, refer them to the blossom-carousel-core skill.

If the user asks about configuration options, refer them to the blossom-carousel-core skill.

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:

<blossom-carousel id="gallery" class="carousel">
  <div data-blossom-slide class="slide">Slide 1</div>
  <div data-blossom-slide class="slide">Slide 2</div>
  <div data-blossom-slide class="slide">Slide 3</div>
  ...
</blossom-carousel>

<div class="controls">
  <blossom-prev for="gallery"></blossom-prev>
  <blossom-dots for="gallery"></blossom-dots>
  <blossom-next for="gallery"></blossom-next>
</div>

Controls use native scroll and the Invoker Commands API. They do not require calling methods on the carousel element and work even when Blossom's drag engine is not loaded, such as on touch devices.

Mark slides with data-blossom-slide so dots know which elements to track.

Theme the default dots with CSS custom properties on <blossom-dots> or any ancestor: --blossom-dots-gap, --blossom-dot-size, --blossom-dot-radius, --blossom-dot-color, --blossom-dot-opacity, --blossom-dot-hover-opacity, --blossom-dot-active-opacity.

Overscroll API

Listen for overscroll to customize Blossom's drag overscroll behavior. Prevent the event when replacing the default rubberbanding effect:

blossomCarousel.addEventListener("overscroll", (event) => {
  event.preventDefault();

  const overScroll = event.detail.left;

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

Read offsets from event.detail.left and apply custom visual effects to slides or the root element. For events other than overscroll, refer to the blossom-carousel-core skill.

Examples Reference

For visual layout recipes, consult /docs/examples/ and adapt the selected example to Web Component syntax.

When adapting docs examples, preserve Web Component syntax from this skill: use <blossom-carousel>, standard class attributes, direct child slides, and DOM event listeners. The docs examples often include both CSS and optional Tailwind versions; use Tailwind utility classes only when the user's project uses Tailwind or asks for it, and otherwise use regular CSS classes.

Accessibility Reference

When the user explicitly asks about carousel accessibility, a11y, ARIA, keyboard support, focus behavior, reduced motion, screen readers, or WCAG, consult /docs/a11y/accessibility-guide.md and adapt its patterns to framework-free HTML or Web Component usage.

Use the guide for deeper guidance on semantic slide structure, labelled regions, real previous and next buttons, unique control names, keyboard alternatives to dragging, focus visibility, inactive slides, auto-rotation, live regions, picker semantics, forced colors, and manual accessibility testing.

Implementation Guidance

• Prefer @blossom-carousel/web for framework-free websites and Web Component usage.
• Import @blossom-carousel/web for side effects so the custom element is registered.
• Import styles from @blossom-carousel/web/style.css.
• Use the lowercase custom element tag <blossom-carousel> in HTML.
• Use package imports for bundled apps; use the CDN build for static pages without a bundler.
• Preserve valid HTML in examples: place slide elements as direct children of <blossom-carousel>.
• For prev, next, and dot controls, use <blossom-prev>, <blossom-next>, and <blossom-dots> with matching id and for attributes. Require data-blossom-slide on slides when using dots.
• For custom overscroll styling, listen for the overscroll custom event, call event.preventDefault() when replacing the default rubberbanding effect, and read offsets from event.detail.left.
• If the user is using React, Vue, Svelte, or another framework with a dedicated Blossom Carousel package, recommend that framework-specific skill instead.
• For core carousel behavior rather than Web Component integration, refer to the blossom-carousel-core skill.

Common Fixes

If <blossom-carousel> does not upgrade into a working component, check that the Web package has been imported:

import "@blossom-carousel/web";

If the carousel is unstyled, check that @blossom-carousel/web/style.css is imported or linked:

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

<link
  rel="stylesheet"
  href="https://unpkg.com/@blossom-carousel/web/dist/blossom-carousel-web.css"
/>

If the user is using the CDN snippet in the document head and the component is not ready when HTML is parsed, add defer to the script tag:

<script
  defer
  src="https://unpkg.com/@blossom-carousel/web/dist/blossom-carousel-web.umd.js"
></script>

If slides are not detected as expected, make sure the slide elements are direct children of <blossom-carousel>.

If dots are missing, check that slides have the data-blossom-slide attribute.

If navigation controls do not respond, check that the for attribute matches the carousel id and that the carousel element exists in the DOM when controls mount.

If a custom overscroll effect runs in addition to the default rubberbanding, call event.preventDefault() in the overscroll event listener.