Configuration options

Configuration example

This is a basic example that starts Omni for a carousel while also passing a few options:

import createOmniCarousel from 'omni-carousel';

const root = document.querySelector('.carousel');

const carousel = createOmniCarousel(root, {
  scrollSteps: 'auto',
  preloadAdjacentImages: true,
  selectors: {
    track: '.carousel-track',
    slide: '.carousel-slide',
    prevButton: '.prev-button',
    nextButton: '.next-button'
  }
});

carousel.init();

Make sure the DOM is ready before selecting your root element!

Default configuration

{
  scrollAlign: 'start', // 'start' | 'center'
  scrollSteps: 'one', // 'one' | 'auto'
  indicatorNumbers: false,
  transitionHelpers: false,
  hasEqualWidths: true,
  preloadAdjacentImages: false,
  selectors: {
    track: '[data-omni-track]',
    slide: '[data-omni-slide]',
    prevButton: '[data-omni-button-prev]',
    nextButton: '[data-omni-button-next]',
    startButton: '[data-omni-button-start]',
    endButton: '[data-omni-button-end]',
    indicatorArea: '[data-omni-indicators]',
    indicator: '[data-omni-indicator]'
  }
}

selectors

Omni has default selectors for the carousel elements it manages or needs to know about. You can change any of those to any valid CSS selectors.

Default:

selectors: {
  track: '[data-omni-track]',
  slide: '[data-omni-slide]',
  prevButton: '[data-omni-button-prev]',
  nextButton: '[data-omni-button-next]',
  startButton: '[data-omni-button-start]',
  endButton: '[data-omni-button-end]',
  indicatorArea: '[data-omni-indicators]',
  indicator: '[data-omni-indicator]'
}

scrollAlign

Default: 'start'
Valid values: 'start' and 'center'

This option is an alternative to setting scroll-snap-align in CSS.

Omni determines the scroll alignment it will use in this order:

• scroll-snap-align value of the first slide (if set)
• scrollAlign value from the configuration if it exists
• 'start' (default)

scrollSteps

Default: 'one'
Valid values: 'one' and 'auto'

This controls how many slides the previous and next buttons scroll at a time: either one or automatically as many as can fit.

Use 'auto' when multiple slides are fully visible per view and you want the buttons to scroll by pages of slides rather than one at a time.

indicatorNumbers

Default: false

Set to true to get numbers in the autogenerated indicators.

transitionHelpers

Default: false

When set to true, Omni adds helper classes to slides as they enter and leave the viewport:

• is-omni-entering for slides entering the viewport
• is-omni-exiting for slides leaving the viewport

These CSS classes can be used to create custom animations or visual effects during transitions.

hasEqualWidths

Default: true

By default Omni assumes all slides are the same width. If you use scrollSteps: 'auto' and slides of different widths, set to false so that each slide is measured separately.

This is important for Omni to be able to calculate correctly how many slides it can bring in at each scroll step.

preloadAdjacentImages

Default: false

Useful for carousels with loading="lazy" in images.

When set to true, Omni removes the loading attribute from one image on each side of the visible slides so that the image starts loading before it enters into view.