Options

Embla Carousel is designed to be highly configurable. Options can be passed as a second argument to the EmblaCarousel constructor in vanilla JavaScript, or as the first argument in framework-specific hooks like useEmblaCarousel.

Usage

Options allow you to control the behavior of the carousel, such as alignment, looping, and drag physics.

import EmblaCarousel from 'embla-carousel'

const viewportNode = document.querySelector('.embla__viewport')
const options = { loop: true, align: 'start' }
const emblaApi = EmblaCarousel(viewportNode, options)

In framework wrappers (React, Vue, Svelte, Solid), options are typically passed directly to the hook:

// React example
const [emblaRef] = useEmblaCarousel({ loop: true, align: 'start' })

Global Options

You can set options globally for all carousels in your application. This is useful for maintaining consistency without repeating configuration.

import EmblaCarousel from 'embla-carousel'

EmblaCarousel.globalOptions = {
  loop: true,
  duration: 30
}

Breakpoints

Embla supports responsive configuration using the breakpoints option. It uses the window.matchMedia API under the hood. The keys in the breakpoints object should be valid CSS media queries.

When a breakpoint matches, the options provided within that breakpoint will be merged with and override the top-level options.

const options = {
  loop: false,
  breakpoints: {
    '(min-width: 768px)': { loop: true },
    '(min-width: 1024px)': { align: 'start' }
  }
}

Reference

Core Configuration

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | active | boolean | true | Enables or disables the carousel. If set to false, it will treat the carousel as a regular container. | | axis | 'x' \| 'y' | 'x' | Sets the scroll axis of the carousel. | | direction | 'ltr' \| 'rtl' | 'ltr' | Sets the content direction. Use 'rtl' for right-to-left languages. | | startSnap | number | 0 | The index of the slide to start on. | | loop | boolean | false | Enables infinite looping. Note: this requires enough slides to fill the viewport width. | | duration | number | 25 | Sets the scroll duration when triggered by API methods (like scrollNext). |

Alignment & Layout

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | align | 'start' \| 'center' \| 'end' \| number | 'center' | Aligns the slides relative to the viewport. Numbers represent a percentage (e.g., 0.5 for center). | | container | string \| HTMLElement | null | The selector or element for the scroll container. Defaults to the first child of the viewport. | | slides | string \| HTMLElement[] | null | The selector or elements to be used as slides. Defaults to the children of the container. | | slidesToScroll | number \| 'auto' | 1 | The number of slides to scroll per interaction. |

Drag & Interaction

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | draggable | boolean | true | Enables mouse and touch interactions. | | dragFree | boolean | false | Enables inertia-based scrolling. Slides will not snap to specific positions unless they come to a natural stop. | | dragThreshold | number | 10 | The distance (in pixels) the user must drag before the carousel starts moving. | | skipSnaps | boolean | false | If true, the carousel will allow skipping multiple snap points when dragging fast. | | focus | boolean | true | If true, the carousel will handle focus events for accessibility. |

Scrolling & Visibility

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | containScroll | false \| 'trimSnaps' \| 'keepSnaps' | 'trimSnaps' | Clears empty space at the beginning or end of the carousel. | | inViewThreshold | number | 0 | A number between 0 and 1 defining how much of a slide must be visible to be considered "in view". | | inViewMargin | string | '0px' | A margin (CSS-like) applied to the viewport for calculating visibility. | | resize | boolean | true | Automatically re-calculates slide dimensions when the window is resized. | | slideChanges | boolean | true | Enables or disables the calculation of slide changes. |

Server-Side Rendering

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | ssr | EmblaOptionsType[] | [] | Used to provide options for server-side rendering environments to ensure initial markup consistency. |