omni-carousel/docs/css-essential-and-recommended.md

A lightweight carousel to enhance scrollable areas

Essential and recommended CSS
================================================================================

Rules that establish a good foundation for a carousel made in CSS

The aim of this document is to extract the essential CSS from the Omni demos.
It also includes patterns that I (Demetris Kikizas) recommend.

Understanding the essential CSS for carousel layout is important because Omni
doesn’t handle layout. Omni simply enhances scrollable areas by managing their
carousel-like UI and by improving keyboard support for navigation.

Note that the “essential” CSS on this page is for carousels using **Flexbox**.
If you use Grid or something else for the layout, the requirements are different.


Useful custom properties
----------------------------------------

Custom properties are not “essential” but I find them useful.
I include a few here for the snippets.

```css
.carousel {
  --slide-width: 200px;
  --slide-height: 200px;

  --indicator-gap: 8px;
  --indicator-width: 24px;
  --indicator-height: 24px;
}
```


Essential CSS
----------------------------------------

```css
[data-omni-track] {
  display: flex;

  overflow-x: auto;
}

[data-omni-slide] {
  flex: none;

  /*
   * width is essential for slides that are Flexbox children.
   * height is situational rather than essential: It can
   * be necessary depending on the desired layout or
   * on the type of elements the slides contain.
   */
  width: var(--slide-width);
  height: var(--slide-height);
}

/*
 * For carousels with indicators (dots)
 */
[data-omni-indicators] {
  display: flex;

  /*
   * Make sure the indicators do not break the layout
   * or disappear if there are too many to fit
   */
  overflow-x: auto;

  /*
   * Hide the scrollbar of the indicators container
   */
  scrollbar-width: none;
}

/*
 * Hide the scrollbar for wayward browsers too
 */
[data-omni-indicators]::-webkit-scrollbar {
  display: none;
}

/*
 * Add this for individual indicators (dots)
 */
[data-omni-indicator] {
  flex: none;

  /*
   * Indicators are autogenerated if there is a container for them.
   * They are button elements and empty by default,
   * so they need both width and height.
   */
  width: var(--indicator-width);
  height: var(--indicator-height);
}
```


Recommended CSS
----------------------------------------

```css
[data-omni-track] {
  scroll-behavior: smooth;
  scroll-snap-type: x mandatory;
}

[data-omni-slide] {
  /*
   * If you set scroll-snap-type for the track,
   * it is recommended to also set scroll-snap-align for the slides.
   * Doing that gives a uniform experience between managed scrolling
   * (managed by Omni) and unmanaged scrolling (touch, scrollbar, etc.)
   * for many common layouts.
   *
   * Use either start or center.
   * Omni reads this value and uses it for managed scrolling.
   */
  scroll-snap-align: center;

  /*
   * Constrain the slide width to avoid surprises
   */
  max-width: 100%;
}
```