Siema - Lightweight and simple carousel with no dependencies

Full docs with examples: https://pawelgrzybek.com/siema/.

Siema is a lightweight (only 2kb gzipped) carousel plugin with no dependencies and no styling. As Brad Frost once said "do that shit yourself". It is 100% open source and available on Github. It is free to use on personal and commercial projects. Use it with your favourite module bundler or by manually injecting the script into your project.

Installation

Setup is trivially easy. A little bit of markup...

<div class="siema">
  <div>Hi, I'm slide 1</div>
  <div>Hi, I'm slide 2</div>
  <div>Hi, I'm slide 3</div>
  <div>Hi, I'm slide 4</div>
</div>

If you are using a module bundler like Webpack or Browserify...

yarn add siema

import Siema from 'siema';
new Siema();

...or manually inject the minified script into your website.

<script src="siema.min.js"></script>
<script>
  new Siema();
</script>

Options

Siema comes with a few (optional) settings that you can change by passing an object as an argument. Default values are presented below.

new Siema({
  selector: '.siema',
  duration: 200,
  easing: 'ease-out',
  perPage: 1,
  mode: 'left',
  freeDrag: false,
  startIndex: 0,
  draggable: true,
  multipleDrag: true,
  threshold: 20,
  loop: false,
  overflowHidden: true,
  onInit: () => {},
  onChange: () => {},
  onDrag: ({ leftOffset, RightOffset }) => {},
});

selector (string or DOM element)
The selector to use as a carousel. Siema will use all immediate children of this selector as a slider items. It can be a query string (example) or DOM element (example).

duration (number)
Slide transition duration in milliseconds (example).

easing (string)
It is like a CSS transition-timing-function — describes acceleration curve (example).

perPage (number or object)
The number of slides to be shown. It accepts a number (example) or an object (example) for complex responsive layouts.

There is also a possibility to pass 0 which enables automatic slides positioning according to mode option.

mode (string)
When automatic slides positioning is enabled, it will change the behaviour of slider when changing the active slide.

Possible values:

Value	Active slide position
left	Always sticks to the left side of a slider container
right	Always sticks to the right side of a slider container
center	Always aligns to the center of a slider container
centerFit	It will be positioned as close to the center as possible while not leaving a free space at any end. In other words, active slide aligns to the center of slider container unless there will be a free space at any end of slider container, in which case the slider will not move any further

freeDrag (boolean)
When dragging slider, it will not change current slide and hence will not reposition slides to fulfill mode property. It will only reposition slides to prevent leaving free space at left or right end.

slideWidth (number)
Width of single slide in pixels used when perPage option is set to 0. If not specified, Siema will try to calculate width based on the first slide.

startIndex (number)
Index (zero-based) of the starting slide (example).

draggable (boolean)
Use dragging and touch swiping (example).

multipleDrag (boolean)
Allow dragging to move multiple slides.

threshold (number)
Touch and mouse dragging threshold (in px) (example).

loop (boolean)
Loop the slides around (example).

overflowHidden (boolean)
Automatically add overflow: hidden; style to main carousel DOM element.

onInit (function)
Runs immediately after initialization (example).

onChange(params) (function)
Runs after slide change (example). params is an object containing currentSlide, leftOffset and rightOffset properties. Those properties denote:

• currentSlide - current slide number
• leftOffset - all slides lane offset from left edge of visible slider (negative number means slides stick out of slider from left side; 0 means they stick to the left side; positive number means there is a gap between leftmost slide and left slider edge)
• rightOffset - all slides lane offset from right edge of visible slider (negative number means slides stick out of slider from right side; 0 means they stick to the right side; positive number means there is a gap between rightmost slide and right slider edge)

onDrag(params) (function)
Runs when slider is being dragged. params is an object containing leftOffset and rightOffset properties. Those properties denote:

• leftOffset - see onChange description
• rightOffset - see onChange description

API

As mentioned above, Siema doesn't come with many options - just a few useful methods. Combine it with some very basic JavaScript and voila!

prev(howManySlides = 1, callback)
Go to previous item (example). Optionally slide few items backward by passing howManySlides (number) argument (example). Optional callback (function) available as a third argument (example).

next(howManySlides = 1, callback)
Go to next item (example). Optionally slide few items forward by passing howManySlides (number) argument (example). Optional callback (function) available as a third argument (example).

goTo(index, callback)
Go to item at particular index (number) (example). Optional callback (function) available as a second argument (example).

remove(index, callback)
Remove item at particular index (number) (example). Optional callback (function) available as a second argument (example).

insert(item, index, callback)
Insert new item (DOM element) at specific index (number) (example). Optional callback (function) available as a third argument (example).

prepend(item, callback)
Prepend new item (DOM element) (example). Optional callback (function) available as a second argument (example).

append(item, callback)
Append new item (DOM element) (example). Optional callback (function) available as a second argument (example).

destroy(restoreMarkup = false, callback)
Remove all event listeners on instance (example). Use restoreMarkup to restore the initial markup inside selector (example). Optional callback (function) available as a third argument (example).

currentSlide
Prints current slide index (example).

Browser support

• IE10
• Chrome 12
• Firefox 16
• Opera 15
• Safari 5.1
• Android Browser 4.0
• iOS Safari 6.0

Extra & Thanks

Siema means 'hello' in Polish. When I play around with some code, I always use random names. That's the whole story behind the name of this one :)

Huge thanks to Jarkko Sibenberg for the cute logo design! I can't thank BrowserStack enough for giving me a free access to their testing amazing service.