Global Options

Global Options

Global options allow you to define default settings for every carousel instance across your entire application. This is especially useful for maintaining consistent behavior—such as specific alignment, loop settings, or drag thresholds—without having to repeat the same configuration object for every initialization.

Setting Global Options

Depending on whether you are using the core library or a framework-specific wrapper, you set global options by assigning an object to the globalOptions static property.

Vanilla JavaScript

If you are using the framework-agnostic core, assign your defaults to the EmblaCarousel constructor.

import EmblaCarousel from 'embla-carousel'

EmblaCarousel.globalOptions = { 
  loop: true, 
  align: 'start' 
}

Framework Hooks (React, Vue, Svelte, Solid)

For framework wrappers, assign the defaults directly to the imported hook or function.

// Example for React (similar for Vue, Svelte, and Solid)
import useEmblaCarousel from 'embla-carousel-react'

useEmblaCarousel.globalOptions = { 
  loop: true,
  duration: 20
}

Option Precedence

Embla Carousel merges options in a specific order of priority. Local options will always override global defaults.

1. Local Options: The options object passed directly to the instance during initialization.
2. Global Options: The options defined via .globalOptions.
3. Library Defaults: The internal default values (e.g., align: 'center', duration: 25).

import EmblaCarousel from 'embla-carousel'

// 1. Set global default
EmblaCarousel.globalOptions = { loop: true }

const emblaNode = document.querySelector('.embla')

// 2. This instance will have 'loop: true' (from global) 
// and 'align: 'start'' (from local)
const emblaApi = EmblaCarousel(emblaNode, { align: 'start' })

TypeScript Support

If you are using TypeScript, the global options property is typed to ensure you only provide valid carousel options. You can also import the EmblaOptionsType to define your options object separately.

import EmblaCarousel, { EmblaOptionsType } from 'embla-carousel'

const customDefaults: EmblaOptionsType = {
  active: true,
  breakpoints: {
    '(min-width: 768px)': { loop: false }
  }
}

EmblaCarousel.globalOptions = customDefaults

Best Practices

• Initialization Timing: Ensure you set globalOptions before initializing any carousel instances. Typically, this is done in your application's entry point (e.g., index.js or main.ts).
• SSR Considerations: When using global options in Server-Side Rendering (SSR) environments, ensure the assignment happens in a location that executes both on the server and the client if you rely on the ssr option or specific breakpoints for layout consistency.