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

Returns: [emblaRef, emblaApi]