Skip to content
A lightweight dependency-free css carousel.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
dist
scripts
src
web
.editorconfig
.eslintignore
.eslintrc
.gitignore
.npmignore
.nvmrc
.sass-lint.yml
.travis.yml
LICENSE
Makefile
README.md
babel.config.js
jest.config.js
package-lock.json
package.json

README.md

CarouCSSel

Build Status Coverage Status on Codecov Known Vulnerabilities

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

Installation

CarouCSSel is available on NPM:

npm install caroucssel --save

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.

@import '~caroucssel/dist/caroucssel';

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

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

JS

The JavaScript enhances the feature set of the carousel by adding buttons and/or pagination. Besides that, some browsers show a scrollbar depending on operating system or settings of the operating system. The JavaScripts detects that appearance and enables the styles to hide them (see options). 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 */ });

Options

Index

Set the initial scroll index. The option format as an array follows API format for possibly multiple visible items (read more). To set an index you need to pass an array with at least one element. When passing more than one, the rest will be ignored.

const carousel = new Carousel(el, {
    index: [42]
});
Buttons

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 set hasButtons to true inside the options object:

const carousel = new Carousel(el, {
    hasButtons: true
});

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

  • buttonClassName – 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'.
  • buttonNext – an object to configure the following options for the next button:
    • className – a string of a class name used to identify this button – Default value is: 'is-next'
    • label – a string of the label for this button – Default value is: 'Next'
    • title – a string of the title for this button – Default value is: 'Go to next'
  • buttonPrevious – an object to configure the following options for the next button:
    • className – a string of a class name used to identify this button – Default value is: 'is-previous'
    • label – a string of the label for this button – Default value is: 'Previous'
    • title – a string of the title for this button – Default value is: 'Go to previous'
  • buttonTemplate – is a function which returns a HTML-string for each button. A data object is passed as param into the invoked function, 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 buttonNext.label and buttonPrevious.label
    • title – a string of the button title defined by buttonNext.title and buttonPrevious.title

A full set of button options could look like this:

const carousel = new Carousel(el, {
    hasButtons: true,
    buttonClassName: 'my-button',
    buttonTemplate: ({className, label, title}) =>
        `<button class="${className}" title="${title}">
            ${label}
        </button>`,
    buttonPrevious: {
        className: 'my-previous-button',
        title: 'Click this button to go one step back',
        label: '<'
    },
    buttonNext: {
        className: 'my-next-button',
        title: 'Click this button to go one step forward',
        label: '>'
    }
});
Pagination

A pagination (or dots) is a list of buttons which 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, set hasPagination to true inside the options object:

const carousel = new Carousel(el, {
    hasPagination: true
});

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

  • paginationClassName – a string which represents the class name for the <ul> element of the pagination – Default value is: 'pagination'
  • paginationLabel – 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
    • item – a dom element reference to the related item
    • items – a dom element list of all items
  • paginationTitle – 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
    • item – a dom element reference to the related item
    • items – a dom element list of all items
  • paginationTemplate– is a function which returns an HTML-string of the complete pagination. The default implementation invokes the paginationLabel and paginationTitle 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 paginationClassName option.
    • controls – a string reference to the HTML id of the carousel element. this is relevant for an aria-controls="..." attribute.
    • items – a dom element list of all items
    • label – the function reference for paginationLabel to create a button label
    • title – the function reference for paginationTitle to create a button tile

A full set of pagination options could look like this:

const carousel = new Carousel(el, {
    hasPagination: true,
    paginationClassName: 'my-pagination',
    paginationLabel: ({index}) => `${index + 1}.`,
    paginationTitle: ({index}) => `Jump to ${index + 1}. item`,
    paginationTemplate: ({className, items, label, title}) =>
        `<div class="${className}">
            ${items.map((item, index) =>
                `<button title="${title({index})}">${label({index})}</button>`
            ).join('')}
        </div>`
});
Scrollbars

To enable the default rendering of the CSS property overflow: auto, set the option hasScrollbars to true.

const carousel = new Carousel(el, {
    hasScrollbars: true
});
Events
  • onScroll a function which is invoked when the user scrolls through the carousel. An object containing the current index (a list of visible indexes), an event type, a reference to the carousel instance (target) and the original scroll event (originalEvent) is passed to the function.

API

SCSS

@include caroucssel()

Adds the minimal set of styles required to display the carousel.

@include caroucssel-snap()

Enables CSS-snapping inside the carousel. The following parameters are available:

  • $at – defines the snap point length. – Default value is: 100%

JS

.index

Returns and/or sets the current index of the carousel. The returned index is a list (array) of indexes that are currently visible (depending on each item width). To set an index you need to pass an array with at least one element. When passing more than one, the rest will be ignored.

.items (read only)

Returns an array of all child dom elements of the carousel.

.id (read only)

Returns the id-attribute value of the carousel.

.el (read only)

Returns the dom element reference of the carousel which was passed into the constructor.

.update()

Enforces an update of all enabled components of the carousel. This is, for example, useful when changing the number of items inside the carousel.

.destroy()

This completely deconstructs the carousel and returns the dom to its initial state.

License

LICENSE (MIT)

You can’t perform that action at this time.