Blossom Carousel Vue

Blossom Carousel Vue

Use this skill for Blossom Carousel Vue or Nuxt tasks involving package installation, component registration, stylesheet setup, <BlossomCarousel> usage examples, root element customization, controls, or overscroll handling.

Blossom Carousel Vue wraps Blossom Carousel Core. For shared carousel behavior, options, lifecycle concepts, events, and engine semantics, also consider the blossom-carousel-core skill.

Package

Install the Vue package:

npm install @blossom-carousel/vue

The Vue package depends on the core package. Always include @blossom-carousel/vue/style.css in app setup unless the user has already imported it elsewhere:

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

Vue Setup

Register BlossomCarousel globally in a Vue app when the user wants to use the component throughout the app:

import { createApp } from "vue";
import { BlossomCarousel } from "@blossom-carousel/vue";
import "@blossom-carousel/vue/style.css";

const app = createApp({});

app.component("BlossomCarousel", BlossomCarousel);

For local component usage, import the component in the Vue file instead of registering it globally:

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

Use TypeScript syntax (<script setup lang="ts">, typed refs like ref<InstanceType<typeof BlossomCarousel> | null>(null)) when the user's project uses TypeScript; otherwise default to JavaScript.

Nuxt Setup

In Nuxt, create a plugin that registers the component globally:

// 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);
});

If the user prefers Nuxt auto-imported components, recommend creating a wrapper component in the app's components directory instead of global plugin registration.

If the user reports hydration mismatches or SSR issues, suggest wrapping <BlossomCarousel> in <ClientOnly> or setting the plugin to client-only via plugins/blossom-carousel.client.ts.

Basic Usage

Use <BlossomCarousel> as the carousel root and pass slides as default slot children:

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

Each direct child becomes a slide. In Vue examples, include :key on v-for slide elements.

Root Element

Use the as prop to define the HTML element rendered for the carousel root:

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

This renders the carousel root as a ul and keeps the slide elements as li children:

<ul>
  <li>Slide 1</li>
  <li>Slide 2</li>
  <li>Slide 3</li>
  ...
</ul>

Match the root element to the slide markup; for list-like carousels, use as="ul" with li slides.

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:

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

<template>
  <BlossomCarousel id="gallery" class="carousel">
    <div v-for="i in 12" :key="i" data-blossom-slide class="slide">
      Slide {{ i }}
    </div>
  </BlossomCarousel>

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

Controls use native scroll and the Invoker Commands API. They do not require a template ref 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.

Use the default slot on <BlossomDots> to replace the built-in dot UI:

<BlossomDots for="gallery">
  <template #default="{ index, active }">
    <span :class="{ active }">{{ index + 1 }}</span>
  </template>
</BlossomDots>

Theme the default dots with CSS custom properties on the component 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 the overscroll event when the user wants to customize Blossom's drag engine overscroll behavior. Prevent the event to replace Blossom's default rubberbanding effect:

<template>
  <BlossomCarousel ref="blossomCarousel" @overscroll.prevent="onOverscroll">
    <div v-for="i in 12" :key="i">Slide {{ i }}</div>
  </BlossomCarousel>
</template>

<script setup>
const blossomCarousel = ref(null);

function onOverscroll(event) {
  const overScroll = event.detail.left;

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

Read overscroll values from event.detail, such as event.detail.left, and apply custom visual effects to the carousel slides or root element. Use a template ref on <BlossomCarousel> when you need the carousel root element, for example to read slide children in an overscroll handler.

Examples Reference

For visual layout recipes, consult /docs/examples/ and adapt the selected example to Vue or Nuxt syntax.

When adapting docs examples, preserve Vue syntax from this skill: use <BlossomCarousel>, class, :key, Vue refs, and Vue event bindings. The docs examples often include both CSS and optional Tailwind versions; use Tailwind utility classes only if the user explicitly mentions Tailwind usage in their project, otherwise default to regular CSS classes.

Migration Reference

If the user is moving from another carousel library, use the blossom-carousel-migration skill first. It routes to the right guide by title and points to the hosted docs page or local source markdown file as needed.

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 Vue or Nuxt syntax.

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/vue for Vue and Nuxt projects.
• Import styles from @blossom-carousel/vue/style.css.
• Use BlossomCarousel as a Vue component, not as a custom element.
• Preserve valid Vue syntax in examples: use :key with v-for, wrap examples in <template> when showing Vue single-file component snippets, and default to script setup unless the user's existing code or explicit request uses the Options API.
• For prev, next, and dot controls, use BlossomPrev, BlossomNext, and BlossomDots with matching id and for props. Require data-blossom-slide on slides when using dots.
• For custom overscroll styling, listen for @overscroll, use .prevent when replacing the default rubberbanding effect, and read offsets from event.detail.left.
• For Nuxt examples, use defineNuxtPlugin and register with nuxtApp.vueApp.component.
• When the user asks about core carousel behavior rather than Vue integration, refer to Blossom Carousel Core concepts and, when available, the blossom-carousel-core skill.

Common Fixes

If the carousel is unstyled, check that this import exists in app setup or the local component:

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

If the component is unknown in Vue templates, check that either:

• BlossomCarousel is imported locally in the component, or
• app.component('BlossomCarousel', BlossomCarousel) is called during Vue app setup, or
• a Nuxt plugin registers the component through nuxtApp.vueApp.component.

If list markup is invalid, use the as prop to align the carousel root with the slide elements, such as as="ul" for li slides.

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

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

If prev or next controls are inactive on touch devices while using imperative carousel methods, switch to BlossomPrev and BlossomNext — they work without the drag engine.

If a custom overscroll effect runs in addition to the default rubberbanding, use @overscroll.prevent="onOverscroll" or call event.preventDefault() in the handler.