Omni Carousel

A JavaScript library to enhance scrollable areas

Omni Carousel is a library that takes CSS-only carousels that work like this and adds enhancements and affordances like these.

Omni Carousel leaves the markup and layout up to the author and focuses on the things you can only do with JavaScript.

Features

• Enhances scrollable areas with:
  • Better keyboard support
  • Button handling (previous/next/start/end)
  • Indicators (that are also navigation controls)
• Adds CSS state classes for conditional styling
• Works with different setups:
  • Responsive slides
  • Full-width slides
  • Fixed-width slides
  • Fixed-width slides of different widths
  • Peek-a-boo slides
• Autodetects scroll alignment from CSS
• Scrolls one slide at a time or as many as fit automatically
• Responds automatically to changes in the track width
• Caches slide and navigation data to reduce DOM queries
• Uses fully configurable CSS selectors
• Sets up lazily (only when needed)
• Uses browser APIs exclusively
• Fully typed

Features not supported

• RTL mode
• Vertical mode
• Dynamic slides
• Customizable scroll duration

Browser support

• Chrome v88+ (Jan 2021)
• Firefox v89+ (Jun 2021)
• Safari v15.4+ (Mar 2022)

In older browsers Omni logs the features it looked for and didn’t find and then exits.

The features Omni checks for are:

1. CSS scroll-behavior
2. CSS aspect-ratio (good rough proxy for several browser APIs)

Quick start

Expected markup

Omni needs three things:

• A root container
• A slide track inside it
• Two or more slides inside the track

<div class="carousel"><!--Root container-->
  <ul data-omni-track><!--Track for the slides-->
    <li data-omni-slide>Slide 1</li><!--Two or more slides-->
    <li data-omni-slide>Slide 2</li>
    <!-- More slides -->
  </ul>
  
  <!--Optional navigation buttons that are handled if present-->
  <button data-omni-button-start>First</button>
  <button data-omni-button-prev>Previous</button>
  <button data-omni-button-next>Next</button>
  <button data-omni-button-end>Last</button>

  <!--Optional container for Omni’s autogenerated indicators-->
  <div data-omni-indicators></div>
</div>

The data-omni-* attributes are the default selectors of Omni. You can change them in the configuration options or add your own classes next to them and use those.

For a complete example with all markup options, see HTML markup.

For the CSS needed to make a functional scroller/carousel, see:

• Essential and recommended CSS
• CSS tips

For conditional styling using the Omni classes, see CSS state classes

Installation

npm install omni-carousel

Initialization

import { createOmniCarousel } from 'omni-carousel';

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

carousel.init();

createOmniCarousel also takes a second argument, for passing configuration options

Example:

createOmniCarousel(root, { scrollSteps: 'auto' });

NOTE. You don’t have to tell Omni anything about the selector you use for the root. Omni just expects a root with a track and two or more slides in the track.

Development

To work on Omni Carousel, first clone the repo and install the dependencies:

git clone https://github.com/demetris/omni-carousel.git
cd omni-carousel
npm install

Then:

• npm run dev — Start the whole project (site and lib) and watch for changes
• npm run lint — Check code style in the TypeScript files
• npm run typecheck — Check the TypeScript types
• cd lib && npm run build — Build the library