omni-carousel/docs/configuration-options.md

A lightweight carousel to enhance scrollable areas

Configuration options
================================================================================


Configuration example
-----------------------------------------

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

```js
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
-----------------------------------------

```js
{
  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:

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