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