CarouCSSel

A lightweight dependency-free css carousel. CSS can scroll, why not use it?

Integrating CarouCSSel with native CSS scroll techniques, including CSS Scroll-driven Animations, is essentially writing CSS. Acting as a wrapper around CSS scrolling, CarouCSSel simplifies the process, even in complex layouts, by providing controls such as buttons or paginations (see Features section). With CarouCSSel, you can effortlessly create dynamic and visually engaging carousels that respond smoothly to user interactions and scrolling events.

• Take a quick tour
• Try the examples
• Read the docs

Docs

• Installation
• Usage
  • CSS
  • SCSS
  • JavaScript / TypeScript
• Features
  • Buttons
  • Pagination
  • Mask (Scrollbars)
  • Mouse
• Options
  • Index
  • Filters
  • Event hooks
• Properties
  • .behavior
  • .index
  • .items (read only)
  • .pages (read only)
  • .pageIndex (read only)
  • .id (read only)
  • .el (read only)
  • .mask (read only)
• Methods
  • .update()
  • .destroy()
• SCSS Mixins

Installation

CarouCSSel is available on NPM:

npm install caroucssel --save

or

yarn add caroucssel

or in the browser

<link rel="stylesheet" href="https://unpkg.com/caroucssel@latest/styles/caroucssel.min.css" />
<script src="https://unpkg.com/caroucssel@latest"></script>

Usage

The carousel is based on two elements. The most important part is the styling. CarouCSSel is shipped with a prebuild CSS-file (for basic usage) and an SCSS-file which contains mixins to set up the carousel. On the other hand, there is a JavaScript class which enhances the carousel by adding controls.

CSS

The prebuild CSS-file only contains selectors for basic usage. It's recommended to use the SCSS-mixins for better customizability. The CSS comes with two class selectors. .caroucssel creates a scrolling area where the child elements are horizontally arranged. The second, optional .use-snap enables basic scroll-snap support at 100% size, aligned to the left.

<link rel="stylesheet" href="caroucssel.min.css">

<div class="caroucssel use-snap">
  <div class="item">Item 1</div>
  <div class="item">Item 2</div>
  <div class="item">Item 3</div>
</div>

SCSS

The SCSS gives the freedom to choose your own selectors, which should have a carousel feature. It also allows you to easily customize the behavior depending on media queries.

@use '~caroucssel' as lib;

.my-carousel {
  @include lib.caroucssel();
  @include lib.caroucssel-snap($at: 100%);

  @media screen and (min-width: 700px) {
    @include lib.caroucssel-snap($at: 50%);
  }
}

JavaScript / TypeScript

Some browsers show a horizontal scrollbar depending on operating system or settings of the operating system. The JavaScripts detects that appearance and attaches some styles to hide them (See Mask feature). On top of that, any other features like buttons or pagination can added as an option. A basic instance of CarouCSSel is created as followed:

import {Carousel} from 'caroucssel';

const el = document.querySelector('.carousel');
const carousel = new Carousel(el, { /* options here */ });

typedocs

Features

CarouCSSel provides a plugin mechanism called "features". Each behavior can be added with a custom feature implementation that is passed as a features list into an instance of the carousel. CarouCSSel comes with a set of predefined features like Buttons and Pagination. All features are tree-shakeable to keep your bundle as small as possible.

Buttons

typedocs

Buttons allow the user to scroll step by step, forwards and backward between items inside the carousel. Buttons are rendered as <button> into the DOM as a direct sibling of the carousel element. By default, the buttons are rendered with required WIA-ARIA attributes. To enable buttons, pass an instance of the feature to the features list:

import {Carousel} from 'caroucssel';
import {Buttons} from 'caroucssel/features/buttons';

const el = document.querySelector('.carousel');
const carousel = new Carousel(el, {
  features: [
    new Buttons(),
  ],
});

Buttons are customizable by additional options. The following options are available:

• className – a string which represents the base class name of both buttons (see other options to change class name for "previous" and "next" button separately) – Default value is: 'button'.
• nextClassName – a string of a class name used to identify this button – Default value is: 'is-next'
• nextLabel – a string of the label for this button – Default value is: 'Next'
• nextTitle – a string of the title for this button – Default value is: 'Go to next'
• previousClassName – a string of a class name used to identify this button – Default value is: 'is-previous'
• previousLabel – a string of the label for this button – Default value is: 'Previous'
• previousTitle – a string of the title for this button – Default value is: 'Go to previous'
• template – is a function which returns a HTML-string for each button. A context object is passed, containing information about:
  • className – a string of class names for the current button
  • controls – a string reference to the HTML id of the carousel element. this is relevant for an aria-controls="..." attribute.
  • label – a string of the button label defined by nextLabel and previousLabel
  • title – a string of the button title defined by nextTitle and previousTitle

A full set of button options could look like this:

import {Carousel} from 'caroucssel';
import {Buttons} from 'caroucssel/features/buttons';

const el = document.querySelector('.carousel');
const carousel = new Carousel(el, {
  features: [
    new Buttons({
      className: 'my-button',
      nextClassName: 'my-next-button',
      nextTitle: 'Click this button to go one step forward',
      nextLabel: '>'
      previousClassName: 'my-previous-button',
      previousTitle: 'Click this button to go one step back',
      previousLabel: '<'
      template: ({className, label, title}) =>
        `<button class="${className}" title="${title}">
          ${label}
        </button>`,
    }),
  ],
});

Pagination

typedocs

The Pagination (or dots) is a list of buttons that allow navigating directly to a specific item/index inside the carousel. By default, the pagination is rendered with required WIA-ARIA attributes. To enable the pagination, pass an instance of the feature to the features list:

import {Carousel} from 'caroucssel';
import {Pagination} from 'caroucssel/features/pagination';

const el = document.querySelector('.carousel');
const carousel = new Carousel(el, {
  features: [
    new Pagination(),
  ],
});

The pagination can be customized by additional options. The following options are available:

• className – a string which represents the class name for the <ul> element of the pagination – Default value is: 'pagination'
• label – a function which returns a string for the label of each button inside the pagination. A data object is passed as param into the invoked function, containing information about:
  • index – a number of the current item index
  • pages – all existing pages, a list of grouped indexes
  • page – the current page
• title – a function which returns a string for the title of each button inside the pagination. A data object is passed as param into the invoked function, containing information about:
  • index – a number of the current item index
  • pages – all existing pages, a list of grouped indexes
  • page – the current page
• template– is a function which returns an HTML-string of the complete pagination. The default implementation invokes the label and title functions to create the string. A data object is passed as param into the invoked function, containing information about:
  • className – a string with the value of the className option.
  • controls – a string reference to the HTML id of the carousel element. this is relevant for an aria-controls="..." attribute.
  • pages – all existing pages, a list of grouped indexes
  • label – the function reference for label to create a button label
  • title – the function reference for title to create a button title

A full set of pagination options could look like this:

import {Carousel} from 'caroucssel';
import {Pagination} from 'caroucssel/features/pagination';

const el = document.querySelector('.carousel');
const carousel = new Carousel(el, {
  features: [
    new Pagination({
      className: 'my-pagination',
      label: ({index}) => `${index + 1}.`,
      title: ({index}) => `Jump to ${index + 1}. item`,
      template: ({className, pages, label, title}) =>
        `<div class="${className}">
          ${pages.map((page, index) =>
            `<button title="${title({index})}">${label({index})}</button>`
          ).join('')}
        </div>`
    }),
  ],
});

Mask (Scrollbars)

typedocs

There is a Mask feature that is used by the Carousel instance by default. In most cases, there is no need to import and apply this feature directly. It's used to calculate and hide the scrollbars. If you would like to opt out of this feature, you need to set the enabled option to false.

import {Carousel, Mask} from 'caroucssel';

const el = document.querySelector('.carousel');
const carousel = new Carousel(el, {
  features: [
    new Mask({
      enabled: false,
    }),
  ],
});

This feature will wrap an element (mask) around the passed element that contains the scrollable items. This mask is used to hide the scrollbar. It is a div element