ESn Slider

33KB ~ 8.0KB gzipped

TL;DR

Slim and modular ES9 javascript slider/carousel library ~ 8.0KB gzipped.

Download GitHub

Default usage

Add the JS and CSS to your markup.

<script src="//cdn.jsdelivr.net/npm/esnext-slider@0.0.9/dist/esnext-slider.js" defer></script>
<link rel="stylesheet" src="//cdn.jsdelivr.net/npm/esnext-slider@0.0.9/dist/css/esnext-slider.css">

Add Slider Markup

<div class="slider">
    <div class="slider__slide">…</div>
    <div class="slider__slide">…</div>
    <div class="slider__slide">…</div>
    <div class="slider__slide">…</div>
</div>

Instantiate Slider

<script>
  new Slider;
</script>

Use with bundler

If you use a package manager install it via npm/yarn

npm i esnext-slider --save

Import l10n, plugins and slider and instantiate slider with custom settings

import de from "esnext-slider/src/l10n/de";
import History from "esnext-slider/src/plugins/history";
import Slider from "esnext-slider"

document.addEventListener('DOMContentLoaded', () => {
  new Slider({
    l10n: de,
    history: {
      base: 'slider',
      write: true,
      read: true,
    }
  });
});

Examples

Showing is better than telling, therefor a little showcase

Pagination

1
2
3
4
5
6

Autoplay

1
2
3
4
5
6

Align

1
2
3
4
5
6

Synchronize Sliders - extended via plugin

1
2
3
4
5
6
1
2
3
4
5
6

History API - extended via plugin

1
2
3
4
5
6

Features

  • BEM class names (configurable)
  • full API access on slider HTMLElement
  • horizontal/vertical mode (Fade mode planned)
  • carousel (Loop) / slider ((not) rewind)
  • pagination (dots, prev, next)
  • align active slide (left, center, right)
  • swipe (touch) and/or drag (mouse) support
  • IntersectionObserver (or polyfill) to change slide visibility (configurable)
  • FPS throttle for slide/resize calculations (24fps)
  • custom events on init, beforeslide, whileslide, whiledrag, afterslide, edgejump and destroy
  • passive events, if supported an applicable
  • stop autoplay on hidden, if supported by browser.
  • l10n of strings, default: en; available: de
  • plugin: history.js: implements HistoryAPI on slider
  • plugin: sync.js: allows syncing of n sliders, e.g. A => B, A <=> B or A <= B

Settings

node

Type:
void/string/HTMLElement

Default value:
void

Description:
Either HTMLElement of Slider or selector of slider(s)

block

Type:
string

Default value:
'slider'

Description:
Block class name

element

Type:
object

Default values:
element.track: 'track'
element.slide: 'slide'
element.pagination: 'pagination'
element.dots: 'dots'
element.dot: 'dot'
element.button: 'button'

Description:
Element class names

modifier

Type:
object

Default values:
modifier.active: 'active'
modifier.visible: 'visible'
modifier.next: 'next'
modifier.prev: 'prev'
modifier.dot: 'dot'
modifier.edge: 'edge'
modifier.horizontal: 'horizontal'
modifier.vertical: 'vertical'
modifier.play: 'play'
modifier.pause: 'pause'
modifier.disabled: 'disabled'

Description:
Modifier class names for states/description of elements

clones

Type:
integer

Default value:
3

Description:
Number of generated clones per edge, if loop is enabled.

transition

Type:
integer

Default value:
250

Description:
Transition time per slide.

multiplyTransition

Type:
bool

Default value:
true

Description:
Multiply transition time if distance is greater than one slider.

ease

Type:
function

Default value:
easeInOutQuart

Description:
Transition easing function with time, start, value, duration as arguments.

align

Type:
enum

Default value:
'left'

Description:
Alignment of slides. Allowed values: left, center or right.

mode

Type:
enum

Default value:
'horizontal'

Description:
Slider mode. Allowed values: horizontal or vertical.

initialSlide

Type:
integer

Default value:
0

Description:
Initial slide on a zero-based index.

slidesToSlide

Type:
integer

Default value:
1

Description:
Number of slides to slide on play, prev or next.

play

Type:
bool/HTMLElement

Default value:
true

Description:
Flag to enable autoplay. If it is a HTMLElement, it will replace the autoplay toggle button.

autoplay

Type:
object

Default values:
autoplay.direction: enum '>'
autoplay.mode: enum 'bounce'
autoplay.duration: integer 3800
autoplay.pauseOnInteraction: bool true

Description:
autoplay.direction: Allowed values: '<' or '>'
autoplay.mode: Allowed values: 'bounce', 'rewind' or 'loop' (needs loop enabled)
autoplay.duration: Duration for autoplay timeout in ms
autoplay.pauseOnInteraction: Flag to toggle autoplay on interaction.

intersection

Type:
object

Default values:
intersection.root: HTMLElement 'this.$slider'
intersection.rootMargin: string '-20px'
intersection.threshold: float 0

Description:
intersection.root:
Element to calculate the intersection against.

intersection.rootMargin:
Adaptions to bounding box of root element.

intersection.threshold:
Value between 0 and 1 that will define the percentage of intersection needed to display/hide slide. 0 is at least 1px

l10n

Type:
object

Default values:
l10n.prev: string 'Previous slide'
l10n.next: string 'Next slide'
l10n.start: string 'Start autoplay'
l10n.pause: string 'Pause autoplay'
l10n.goto: string 'Go to slide %d'
l10n.active: string 'Go to current slide'
l10n.nav: string 'Go to slider pagination'

Description:
l10n.prev: Title for prev button
l10n.next: Title for next button
l10n.start: Title for play button, if autoplay.stop is enabled
l10n.pause: Title for play button, if autoplay.stop is disabled
l10n.goto: Title for dot %d
l10n.active: Title for current slide shortcut (not implemented)
l10n.nav: Title for pagination shortcut (not implemented)

Settings for: sync.js

syncedSliders

Type:
NodeList/Array of HTMLElements

Description:
If the provided elements have a slider attribute (are instantiated), the current slider will sync its movements with them.

Settings for: history.js

You must add all settings if you want to use the history.js plugin.

history

Type:
object

Needed keys:
history.base: string
history.write: bool
history.read: bool

Description:
history.base:
Will be the unique identifier within your location.hash. The base is needed for history.read and/or history.write.

history.write:
If enabled, each slide change will push in your browsers history. On popstate slider will slide to those pushes.

history.read:
If enabled, the event popstate will check for the presence of history.base and the slide id index + 1). The slider will slide to the given slide if possible.

API

Available methods & settings. The API is also exposed in the HTMLElement as attribute slider.slider and can be extended by plugins.

slider.$$slides

An array of all your slides (without clones).

slider.settings

If you want to mutate the slider instance.

slider.prev()

Slides to prev slide. It will slide slidesToSlide in length, if possible.

slider.to( slide )

Slides to slide with index slide. The slide index is zero based.

slider.next()

Slides to next slide. It will slide slidesToSlide in length, if possible.

slider.destroy()

Destroy slider and remove all event listeners.

slider.reInit()

To re-initialize a destroyed slider.

slider.synced - extended via sync.js

Boolean to prevent endless loops while syncing (if sliders sync each other)

Events

Custom events you can hook into to enhance/extend your slider. Both shipped plugins (history.js & sync.js) use those Events.

init

Arguments:
slider -

Description:
Will be fired just before slider initialization.

beforeslide

Arguments:
slider - Instance of slider
current - Zero-based slide index of current slide
next - Zero-based slide index of target slide
isEdgeSlide - true or false indicates that an edge will be jumped

Description:
Will be fired before sliding to the next slide. If dragToSlide/swipeToSlide is enabled, this event will be fired on drag/swipe start, without next or isEdgeSlide If loop is enabled isEdgeSlide indicates an edge jump.

afterslide

Arguments:
slider - Instance of slider
current - Zero-based slide index of current slide
isEdgeSlide - true or false indicates that an edge will be jumped

Description:
Will be fired after sliding to the current slide. If loop is enabled isEdgeSlide indicates an edge jump.

whiledrag

Arguments:
slider - Instance of slider
direction - '<' or '>' indicates drag direction
distance - object dragged distance in px
origin - object original track position

Description:
Will be fired during drag/swipe.

whileslide

Arguments:
slider - Instance of slider
direction - '<' or '>' indicates slide direction
distance - total distance to transform in px
distancePassed - distance transformed in px
transition - total transition time in ms
transitionPassed - passed transition time in ms

Description:
Will be fired during sliding.

edgejump

Arguments:
slider - Instance of slider
direction - < or > indicate jump direction.

Description:
Event is fired after an edge jump. The edge does only exist if loop is enabled and a clone is the next slide.

destroy

Arguments:
slider - Instance of slider
$slider - $slider HTMLElement to bind event listeners to.

Description:
Will be fired after slider destruction.

slideend - internal

Description:
Event is immediately fired after transition is ended but before magic is happening. This Event is triggered on the track and not the slider itsself.