a-simple-carousel

Simple Carousel

A vanilla JS, performant, accessible implementation of a carousel UI element.

Major Features:

• Vanilla JS: works with your build with no extra frameworks
• Performant: uses proper render layers to ensure high performance

---

• Quickstart
• Creating a Carousel
  • Preparing the HTML
  • Initializing the Carousel
• API
  • Carousel.next()
  • Carousel.previous()
• Options
  • Element
  • Selector
  • Movement Increment
  • Movement Unit

Quickstart

Note: this quickstart requires webpack and NPM

First, get Simple Carousel from NPM:

npm i --save a-simple-carousel

Then import SimpleCarousel from that package:

import {SimpleCarousel} from "a-simple-carousel";

Then just follow the Creating a Carousel documentation below to get up and running.

Creating a Carousel

Preparing the HTML

A Carousel requires a small amount of specific HTML to work properly. Most notably, the carousel element requires that there be a "tray" element wrapping around the actual Carousel contents. By default, Simple Carousel looks for an element beneath the Carousel element with the class of tray, but this can be configured using the tray selector option.

Otherwise, no styles or additional configuration need be added; the rest is handled by the Carousel object when it is initalized.

Example:

<div id="my-carousel">
    <div class="tray">
        <!-- carousel items go here -->
    </div>
</div>

Initializing the Carousel

There are two ways to create a Carousel, both of which involves the global symbol SimpleCarousel. You can either use the SimpleCarousel.init() which returns a Carousel instance, or you can instantiate the instance yourself using SimpleCarousel.Carousel() constructor.

Either way, the init() method or the Carousel() constructor take the same configuration object, which is documented below.

Examples:

Creating a slider using the init method

var carousel = SimpleCarousel.init({
    element: document.getElementById("my-carousel")
});

Creating a slider using the constructor

var carousel = new SimpleCarousel.Carousel({
    selector: "#my-carousel"
});

API

Either calling the Carousel constructor or using the init() method will return a Carousel object, on which the below methods can be found.

Carousel.next()

Moves the Carousel forward by one increment of distance (by default, one screen-length), assuming that that Carousel is not in the middle of moving already and the Carousel is not at the end of its track.

Example:

var carousel = SimpleCarousel.init({
    element: document.getElementById("my-carousel")
});

carousel.next();

Carousel.previous()

Moves the Carousel backwards by one increment of distance (by default, one screen-length), assuming that the Carousel is not in the middle of moving already and the Carousel is not and the beginning of its track.

Example:

var carousel = SimpleCarousel.init({
    element: document.getElementById("my-carousel")
});

carousel.previous();

Options

Below are the options that can be passed to the init() method or the constructor to configure how the carousel works.

The only required option is you must specify an element for the carousel to connect to, either via the config.element option or the config.selector option.

Element

Required: Yes (if Selector option is not specified)
Value: HTMLElement Default: n/a
Key: element

Used to specify the HTMLElement that the Carousel should connect to. Must be specified if no element selector is specified.

Selector

Required: Yes (if Element option is not specified)
Value: String Default: n/a
Key: selector

The CSS selector specifying the element that the Carousel should connect to. Must be specified if no element selector is specified.

Movement Increment

Required: No
Value: Integer
Default: 100
Key: movementIncrement

The increment of movement that the carousel moves every time that next() or previous() is called. This is based on the movement unit setting, so for example, if the movement unit is set to % and the movement increment is set to 50, then calling next() would move the slider 50% to the left.

Movement Unit

Required: No
Value: String
Default: %
Key: movementUnit

The unit to be applied to the movement increment (see movement increment). Accepts any valid CSS unit.

Tray Selector

Required: No
Value: String
Default: .tray
Key: traySelector

The CSS selector specifying the tray element. This selector is relative to the parent Carousel element.

If you are not sure what the tray element is or what it is for, please see the preparing the HTML section.