omni-carousel/README.md

A lightweight carousel to enhance scrollable areas

Omni Carousel
================================================================================

A JavaScript library to enhance scrollable areas


Omni Carousel is a library that takes [CSS-only carousels that work like this](https://omnicarousel.dev/demos/no-js/) and [adds enhancements and affordances like these](https://omnicarousel.dev/demos/one-per-view/).

Omni Carousel leaves the markup and layout up to the author
and focuses on the things you cannot do without 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

```html
<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](docs/configuration-options.md)
or add your own classes next to them and use those.

For a complete example with all markup options, see [HTML markup](docs/html-markup.md).

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

-   [Essential and recommended CSS](docs/css-essential-and-recommended.md)
-   [CSS tips](docs/css-tips.md)

For conditional styling using the Omni classes, see
[CSS state classes](docs/css-state-classes.md)


### Installation

```bash
npm install omni-carousel
```


### Initialization

```js
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](docs/configuration-options.md)

Example:

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

```bash
#
# Clone and install 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