Vue and Nuxt
Install
pnpm add @blossom-carousel/vue
bun add @blossom-carousel/vue
yarn add @blossom-carousel/vue
npm install @blossom-carousel/vue
Local component usage
<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.
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.
<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.
<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.
<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:
/* 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.
<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).
<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:
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 and Dots examples for live demos.
Overscroll API
Tap into Blossom's drag engine's overscroll behavior to create your own style.
<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>