Skip to content

Latest commit

 

History

History
247 lines (180 loc) · 10.1 KB

README.md

File metadata and controls

247 lines (180 loc) · 10.1 KB
Raw

simple-slider

NPM version CDNJS version Build Status File Size: < 1.1kB gzipped license Join the chat at https://gitter.im/simple-slider/Lobby

https://ruyadorno.github.io/simple-slider

Extremely lightweight carousel micro library.

Build Status

About

simple-slider is a carousel micro library based on the requestAnimationFrame API. It makes for a highly testable implementation and less css-dependent.

This package contains a framework agnostic implementation. If you are using AngularJS or Polymer there are some simple-slider framework-specific implementations available:

Features

  • Small size, less than 1.1kb minified/gzipped
  • Support to UMD: AMD, CommonJS and global definition
  • Uses requestAnimationFrame for animations
  • Supports Page visibility API to pause/resume transitions when user navigates away from the page
  • Accept ease functions to customize the transition animation
  • Lots of ready-to-use examples available, just check the example folder
  • Animates any numerical css property

Install

Available on npm:

npm install --save simple-slider

and you can also get it on Bower:

bower install --save simple-slider

Getting it from cdnjs

This library is also available on https://cdnjs.com/ you can use it just by importing:

Usage

Simply import the script in your html and call the simpleslider.getSlider function.

<div style="width:612px; height:612px" data-simple-slider>
  <img src="https://picsum.photos/612/612?random=1"/>
  <img src="https://picsum.photos/612/612?random=2"/>
</div>
<script src="https://cdnjs.cloudflare.com/ajax/libs/simple-slider/1.0.0/simpleslider.min.js"></script>
<script>
  simpleslider.getSlider();
</script>

In this previous example we didn't specified any additional option, in this case the slider will use its default left-to-right sliding animation and the container element will be the first element containing a data-simple-slider attribute.

Usage in a CommonJS environment

var simpleslider = require('simple-slider');

simpleslider.getSlider();

ES2015+ environments

import { getSlider } from 'simple-slider/src';

getSlider();

RequireJS/AMD environment

require(['simple-slider'], function(simpleslider) {
  simpleslider.getSlider();
});

Options

Options are set as named properties of a single parameter accepted by the getSlider function, they help you customize the slider transition and how it's going to work.

The main option is a container element, this will usually be a <div> or <ul> containing the elements to be transitioned, keep in mind that this container should also have a defined width/height value. You can also tweak things such as the delay time between each transition, how long each transition will take, etc.

<div id="myslider" style="width:612px; height:612px">
  <img src="https://picsum.photos/612/612?random=1"/>
  <img src="https://picsum.photos/612/612?random=2"/>
</div>
<script src="https://cdnjs.cloudflare.com/ajax/libs/simple-slider/1.0.0/simpleslider.min.js"></script>
<script>
  simpleslider.getSlider({
    container: document.getElementById('myslider'),
    transitionTime:1,
    delay:3.5
  });
</script>

Available Options

Here is the list of available values to customize how your slider is going to work:

  • container: <Element> The HTML element that act as a container for the slider. Defaults to document.querySelector('*[data-simple-slider]).
  • children <NodeList/Array> A list of children to be used as slides, you can use the querySelectorAll to have more flexibility on what children of the container element should be used as slides. Defaults to container.children.
  • paused: Controls carousel auto-transition/slideshow. If value is true no transition will happen. Defaults to false.
  • prop: Determines the css property to be animated. Defaults to left.
  • duration: Value setting the duration of animation transition. Defaults to 0.5.
  • delay: Value determining the wait between each animation when auto-transition is enabled. Defaults to 3 seconds.
  • init: <String/Number> Initial value of slide elements when starting a transition animation. Defaults to -100.
  • show: <String/Number> The value a slide element should have when it is displayed. Defaults to 0.
  • end: <String/Number> The value a slide will move to during a transition animation. Defaults to 100.
  • unit: The css unit value to be used. Defaults to %.
  • ease: An ease function, you can use any of these. Defaults to defaultEase internal function.
  • onChange: A callback function to be invoked each time a slide changes.
  • onChangeEnd: A callback function to be invoked at the end of the slide transition

Default values

{
  container: document.querySelector('*[data-simple-slider]'),
  children: container.children,
  paused: false,
  prop: 'left',
  duration: 0.5,
  delay: 3,
  init: -100,
  show: 0,
  end: 100,
  unit: '%',
  ease: defaultEase function,
  onChange: undefined,
  onChangeEnd: undefined
}

Programmatic API

Some methods are exposed by the returning value of the function allowing you to control the slider.

<div id="myslider" style="width:612px; height:612px">
  <img src="http://placekitten.com/g/612/612"/>
  <img src="http://placekitten.com/g/612/613"/>
</div>
<script src="../dist/simpleslider.min.js"></script>
<script>
  var currentIndex;

  function updateCurrentIndex() {
    currentIndex = slider.currentIndex();
  }

  var slider = simpleslider.getSlider({
    container: document.getElementById('myslider'),
    onChangeEnd: updateCurrentIndex
  });

  // pauses slideshow
  slider.pause();
</script>

Available methods:

  • currentIndex() Returns the index of the current displaying image.
  • pause() Pauses the slideshow.
  • resume() Resumes the slideshow.
  • reverse() Swaps init for end and reverses the order of slides.
  • nextIndex() Gets the index of the next slide to be shown.
  • prevIndex() Gets the index of the previous slide.
  • next() Switches displaying image to the next one.
  • prev() Switches displaying image to the previous one.
  • change(index) Changes image to a given index value.
  • dispose() Disposes of all internal variable references.

More examples

Documentation

Extensive documentation of the options and methods can be found at the simple-slider official documentation.

Alternatives

A JavaScript carousel micro library is not a new thing (fun fact, simple-slider has been around since 2013).

I would recommend that you take a look at some of the available alternatives and decide by yourself which one better suits your needs.

License

MIT © Ruy Adorno