options.mdx

title	description	order	date
Options	Discover how to customize Embla Carousel with its available options.	0	2021-02-21

import { Tabs } from 'components/Tabs/Tabs' import { TabsItem } from 'components/Tabs/TabsItem'

Options

Embla Carousel takes various options in order to customize how the carousel works. You can provide options in two different ways.

Usage

You can customize Embla with the constructor options and/or global options. If both are provided, they will be merged, and if any options are in conflict, the constructor option has precedence and will override global options.

Constructor options

The constructor options is the default way of providing options to Embla Carousel. In the following example, the carousel loop option is set to true:

import EmblaCarousel from 'embla-carousel'

const emblaApi = EmblaCarousel(emblaNode, { loop: true })

import useEmblaCarousel from 'embla-carousel-react'

export const EmblaCarousel = () => {
  const [emblaRef] = useEmblaCarousel({ loop: true })
  // ...
}

<script>
  import emblaCarouselVue from 'embla-carousel-vue'

  export default {
    setup() {
      const [emblaNode] = emblaCarouselVue({ loop: true })
      // ...
    },
  }
</script>

Note that it's possible to **change options** passed to the Embla Carousel constructor **after initialization** with the [reInit](/api/methods/#reinit) method.

Global options

Setting global options will be applied to all carousels which will override the Embla default options with your own. In the following example loop is set to true:

import EmblaCarousel from 'embla-carousel'

EmblaCarousel.globalOptions = { loop: true }

const emblaApi = EmblaCarousel(emblaNode, { align: 'center' })

import useEmblaCarousel from 'embla-carousel-react'

useEmblaCarousel.globalOptions = { loop: true }

export const EmblaCarousel = () => {
  const [emblaRef] = useEmblaCarousel({ align: 'center' })
  // ...
}

<script>
  import emblaCarouselVue from 'embla-carousel-vue'

  emblaCarouselVue.globalOptions = { loop: true }

  export default {
    setup() {
      const [emblaNode] = emblaCarouselVue({ align: 'center' })
      // ...
    },
  }
</script>

Make sure to assign global options **before** initializing any carousel and **only assign it once**. Re-assigning global options might lead to confusing code and unexpected behaviour.

---

Reference

Below follows an exhaustive list of all Embla Carousel options and their default values.

active

Type: boolean
Default: true

Setting this to false will not activate or deactivate the carousel. Useful when used together with the breakpoints option to toggle the carousel active/inactive depending on media queries.

align

Type: string | number
Default: center

Align the slides relative to the carousel viewport. Use one of the predefined alignments start, center or end. Alternatively, provide a number between 0 - 1 to align the slides, where 0.5 equals 50%.

axis

Type: string
Default: x

Choose scroll axis between x and y. Remember to stack your slides horizontally or vertically using CSS to match this option.

breakpoints

Type: EmblaOptionsType
Default: {}

An object with options that will be applied for a given breakpoint by overriding the options at the root level. Example: '(min-width: 768px)': { loop: false }. Note: If multiple queries match, they will be merged. And when breakpoint options clash, the last one in the list has precedence.

container

Type: string | HTMLElement | null
Default: null

Enables choosing a custom container element which holds the slides. By default, Embla will choose the first direct child element of the root element. Provide either a valid CSS selector string or a HTML element.

containScroll

Type: string
Default: ''

Clear leading and trailing empty space that causes excessive scrolling. Use trimSnaps to only use snap points that trigger scrolling or keepSnaps to keep them.

direction

Type: string
Default: ltr

Choose content direction between ltr and rtl. Please note that when using rtl, the content direction also has to be set to RTL, either by using the HTML dir attribute or the CSS direction property.

dragFree

Type: boolean
Default: false

Enables momentum scrolling. The speed and duration of the continued scrolling is proportional to how vigorous the drag gesture is.

draggable

Type: boolean
Default: true

Enables for scrolling the carousel with mouse and touch interactions.

inViewThreshold

Type: number
Default: 0

Choose a fraction representing the percentage portion of a slide that needs to be visible in order to be considered in view. For example, 0.5 equals 50%.

loop

Type: boolean
Default: false

Enables infinite looping. Automatically falls back to false if slide content isn't enough to loop. Embla will apply translateX or translateY to the slides that need to change position in order to create the loop effect.

skipSnaps

Type: boolean
Default: false

Allow the carousel to skip scroll snaps if it's dragged vigorously. Note that this option will be ignored if the dragFree option is set to true.

slides

Type: string | HTMLElement[] | NodeListOf<HTMLElement> | null
Default: null

Enables using custom slide elements. By default, Embla will choose all direct child elements of its container. Provide either a valid CSS selector string or a nodeList/array containing HTML elements.

slidesToScroll

Type: string | number
Default: 1

Group slides together. Drag interactions, dot navigation, and previous/next buttons are mapped to group slides into the given number, which has to be an integer. Set it to auto if you want Embla to group slides automatically.

speed

Type: number
Default: 10

Adjust scroll speed when triggered by any of the API methods. Higher numbers enables faster scrolling. Drag interactions are not affected because speed is then determined by the drag force. Only values between 1-20 are recommended.

Note: The speed option is actually controlling the magnitude of the attraction force to the target (where the carousel is headed). This is because Embla uses a simple physics simulation when scrolling instead of transitions.

startIndex

Type: number
Default: 0

Set the initial scroll snap to the given number. First snap index starts at 0. Please note that this is not necessarily equal to the number of slides when used together with the slidesToScroll option.