Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ruyadorno/simple-slider
:carousel_horse: The 1kb JavaScript Carousel
https://github.com/ruyadorno/simple-slider
carousel html javascript javascript-carousel js micro-library slide slide-transitions slider transition-animation
Last synced: 13 days ago
JSON representation
:carousel_horse: The 1kb JavaScript Carousel
- Host: GitHub
- URL: https://github.com/ruyadorno/simple-slider
- Owner: ruyadorno
- License: mit
- Created: 2013-05-22T17:09:13.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2023-03-01T15:37:04.000Z (over 1 year ago)
- Last Synced: 2024-10-17T03:13:55.214Z (27 days ago)
- Topics: carousel, html, javascript, javascript-carousel, js, micro-library, slide, slide-transitions, slider, transition-animation
- Language: JavaScript
- Homepage: https://ruyadorno.github.com/simple-slider
- Size: 2.52 MB
- Stars: 613
- Watchers: 27
- Forks: 60
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# simple-slider
[](https://npmjs.org/package/simple-slider)
[](https://cdnjs.com/libraries/simple-slider)
[](https://travis-ci.org/ruyadorno/simple-slider)
[](https://raw.githubusercontent.com/ruyadorno/simple-slider/master/LICENSE)
[](https://gitter.im/simple-slider/Lobby)
https://ruyadorno.github.io/simple-slider
Extremely lightweight carousel micro library.
[](https://saucelabs.com/beta/builds/533bdd25630b4472a05f128b0c47e91f)
## About
**simple-slider** is a carousel micro library based on the [requestAnimationFrame](https://developer.mozilla.org/en-US/docs/Web/API/window/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:
- [angular-simple-slider](https://github.com/ruyadorno/angular-simple-slider)
- [polymer-simple-slider](https://github.com/ruyadorno/polymer-simple-slider)
## Features
- Small size, less than 1.1kb minified/gzipped
- Support to [UMD](https://github.com/umdjs/umd): AMD, CommonJS and global definition
- Uses [requestAnimationFrame](https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame) for animations
- Supports [Page visibility API](https://developer.mozilla.org/en-US/docs/Web/Events/visibilitychange) to pause/resume transitions when user navigates away from the page
- Accept [ease functions](https://github.com/jimjeffers/Easie/blob/master/easie.js) to customize the transition animation
- Lots of ready-to-use examples available, just check the [example](./examples/) folder
- Animates any numerical css property
## Install
Available on **npm**:
```sh
npm install --save simple-slider
```
and you can also get it on **Bower**:
```sh
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:
- Minified version: https://cdnjs.cloudflare.com/ajax/libs/simple-slider/1.0.0/simpleslider.min.js
- Unminified version: https://cdnjs.cloudflare.com/ajax/libs/simple-slider/1.0.0/simpleslider.js
## Usage
Simply import the script in your html and call the `simpleslider.getSlider` function.
```html
simpleslider.getSlider();
```
*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
```js
var simpleslider = require('simple-slider');
simpleslider.getSlider();
```
### ES2015+ environments
```js
import { getSlider } from 'simple-slider/src';
getSlider();
```
### RequireJS/AMD environment
```js
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 `
` or `` 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.
```html
simpleslider.getSlider({
container: document.getElementById('myslider'),
transitionTime:1,
delay:3.5
});
```
### Available Options
Here is the list of available values to customize how your slider is going to work:
- **container**: <[Element](https://developer.mozilla.org/en-US/docs/Web/API/Element)> The HTML element that act as a container for the slider. Defaults to `document.querySelector('*[data-simple-slider])`.
- **children** <[NodeList](https://developer.mozilla.org/en-US/docs/Web/API/NodeList)/Array> A list of children to be used as slides, you can use the [querySelectorAll](https://developer.mozilla.org/en-US/docs/Web/API/Document/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**: Initial value of slide elements when starting a transition animation. Defaults to `-100`.
- **show**: The value a slide element should have when it is displayed. Defaults to `0`.
- **end**: 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](https://github.com/jimjeffers/Easie/blob/master/easie.js). 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
```js
{
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.
```html
var currentIndex;
function updateCurrentIndex() {
currentIndex = slider.currentIndex();
}
var slider = simpleslider.getSlider({
container: document.getElementById('myslider'),
onChangeEnd: updateCurrentIndex
});
// pauses slideshow
slider.pause();
```
### 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
- [Responsive layout example](./examples/responsive-layout-example.html)
- [Default slider with no options](./examples/no-options.html)
- [Default slider with options](./examples/default-sliding-transition.html)
- [Fading/Opacity transition](./examples/fading-transition.html)
- [Full page transition](./examples/full-page-transition.html)
- [Lightbox integrated](./examples/lightbox-integrated-example.html)
- [Mask sliding transition](./examples/mask-sliding-transition.html)
- [Pause slide](./examples/pause-slide-change-example.html)
- [RequireJS usage](./examples/requirejs-example.html)
- [Reverse sliding direction](./examples/reverse-sliding-direction-example.html)
- [Right to left sliding transition](./examples/right-to-left-sliding-transition.html)
- [Slides containing no images](./examples/text-content-example.html)
- [Top to bottom transition](./examples/top-to-bottom-sliding-transition.html)
- [Touch swipe example](./examples/touch-swipe-example.html)
- [Custom ease animation](./examples/custom-ease-animation-example.html)
## [Documentation](https://ruyadorno.github.io/simple-slider/docs/)
Extensive documentation of the options and methods can be found at the [simple-slider official documentation](https://ruyadorno.github.io/simple-slider/docs/).
## Alternatives
A JavaScript carousel micro library is not a new thing (fun fact, **simple-slider** has been around [since 2013](https://github.com/ruyadorno/simple-slider/commit/1e54f82536e5e1ef047445ab705c674cff3db9ee)).
I would recommend that you take a look at some of the available alternatives and decide by yourself which one better suits your needs.
- [slick](https://github.com/kenwheeler/slick)
- [lory](https://github.com/meandmax/lory)
- [siema](https://pawelgrzybek.com/siema/)
- [Swiper](https://github.com/nolimits4web/Swiper)
- [iSlider](https://github.com/BE-FE/iSlider)
- [Owl Carousel](https://github.com/OwlCarousel2/OwlCarousel2)
- [flickity](https://github.com/metafizzy/flickity)
- [swipe](https://github.com/lyfeyaj/swipe)
- [unslider](https://github.com/idiot/unslider)
- [Glide](https://github.com/jedrzejchalubek/glidejs)
## License
MIT © [Ruy Adorno](http://ruyadorno.com)