Vue
Installation
To start using Embla Carousel in your Vue project, install the package along with the core library:
npm install embla-carousel-vue embla-carousel
Basic Usage
The useEmblaCarousel hook provides a reactive way to integrate Embla into your components. It requires a template ref to be attached to the viewport element.
<script setup>
import useEmblaCarousel from 'embla-carousel-vue'
// emblaRef is used to bind the viewport element
// emblaApi is a reactive reference to the carousel instance
const [emblaRef, emblaApi] = useEmblaCarousel()
</script>
<template>
<div class="embla" ref="emblaRef">
<div class="embla__container">
<div class="embla__slide">Slide 1</div>
<div class="embla__slide">Slide 2</div>
<div class="embla__slide">Slide 3</div>
</div>
</div>
</template>
<style scoped>
.embla {
overflow: hidden;
}
.embla__container {
display: flex;
}
.embla__slide {
flex: 0 0 100%;
min-width: 0;
}
</style>
Configuration
Options
You can pass an options object as the first argument to useEmblaCarousel. These options control the carousel's behavior, such as looping, alignment, and drag sensitivity.
<script setup>
import useEmblaCarousel from 'embla-carousel-vue'
const options = { loop: true }
const [emblaRef] = useEmblaCarousel(options)
</script>
Plugins
Plugins are passed as the second argument in an array.
<script setup>
import useEmblaCarousel from 'embla-carousel-vue'
import Autoplay from 'embla-carousel-autoplay'
const [emblaRef] = useEmblaCarousel({ loop: false }, [Autoplay()])
</script>
Global Options
To set default options for all carousels in your application, use the globalOptions property.
import useEmblaCarousel from 'embla-carousel-vue'
useEmblaCarousel.globalOptions = { loop: true }
Accessing the API
The emblaApi returned by the hook is a Vue ref. Because the carousel initializes after the component is mounted, you should access the API inside a watch effect or a lifecycle hook.
<script setup>
import { watch } from 'vue'
import useEmblaCarousel from 'embla-carousel-vue'
const [emblaRef, emblaApi] = useEmblaCarousel()
watch(emblaApi, (api) => {
if (!api) return
api.on('select', () => {
console.log(`Current slide index is: ${api.selectedSnap()}`)
})
})
</script>
TypeScript Support
The embla-carousel-vue package is written in TypeScript and provides types for options, plugins, and the API instance.
<script setup lang="ts">
import { watch } from 'vue'
import useEmblaCarousel from 'embla-carousel-vue'
import type { EmblaOptionsType, EmblaCarouselType } from 'embla-carousel'
const options: EmblaOptionsType = { align: 'start' }
const [emblaRef, emblaApi] = useEmblaCarousel(options)
watch(emblaApi, (api: EmblaCarouselType | undefined) => {
if (api) {
// TypeScript now recognizes api methods
console.log(api.slideNodes())
}
})
</script>
API Reference
useEmblaCarousel(options, plugins)
| Argument | Type | Description |
| :--- | :--- | :--- |
| options | EmblaOptionsType | Configuration options for the carousel. |
| plugins | EmblaPluginType[] | An array of plugins to extend functionality. |
Returns: [emblaRef, emblaApi]
| Return Value | Type | Description |
| :--- | :--- | :--- |
| emblaRef | Ref<HTMLElement> | A Vue template ref to be bound to the carousel viewport element. |
| emblaApi | Ref<EmblaCarouselType \| undefined> | A reactive reference to the Embla API instance, available once mounted. |