Tiny Slider

Vanilla javascript slider for all purposes.

Slider
ganlanyuan/tiny-slidertiny-slider

README

Tiny Slider 2 undefined

version

Tiny slider for all purposes, inspired by Owl Carousel.

Demos

Test results
<!-- Tests for desktop browsers (running on Firefox 12+, Chrome 15+, Safari 5.1+, Opera 12.1+, IE9+)
Tests for mobile browsers  (running on Android Browser 4.2+)
-->

Previous versions:
v1,
v0

Warning: tiny-slider works with static content and it works in the browser only. If the HTML is loaded dynamically, make sure to call tns() after its loading.

Contents

+ What's new
+ Features
+ Install
+ Usage
+ Options
+ Responsive options
+ Methods
+ Custom Events
+ Fallback
+ Browser Support
+ Support
+ License

What's new

- Using % instead of px (No more recalculation of each slide width on window resize)
- Using CSS Mediaqueries if supported
- Save browser capability values to localStorage, so they will not be recheck again until browser get upgraded or user clear the localStorage manually.
- More options available for responsive. (Start from v2.1.0, issue 53)
- Insert controls and nav _before_ slider instead of after (issue 4)
- Move autoplay button out of nav container. (Start from v2.1.0)
- Some selector changes in [tiny-slider.scss](https://github.com/ganlanyuan/tiny-slider/blob/master/src/tiny-slider.scss)

Migrating to v2
- Update controls and / or nav styles based on their position changes.
- Update the [slider selectors](https://github.com/ganlanyuan/tiny-slider/blob/master/src/tiny-slider.scss) accordingly if used in your CSS or JS.
- Update styles related to autoplay button.

top↑

Features

  Carousel * Gallery
Horizontal * Vertical
Percentage Width * Fixed Width Auto Width
Loop ✓ ✓ ✓ ✓ ✓
Rewind ✓ ✓ ✓ ✓  
Slide by ✓ ✓ ✓ ✓  
Gutter ✓ ✓ ✓ ✓ ✓
Edge padding ✓ ✓ ✓ ✓  
Center (v2.9.2+) ✓ ✓ ✓    
Responsive ✓ ✓ ✓ ✓ ✓
Lazyload ✓ ✓ ✓ ✓ ✓
Autoplay ✓ ✓ ✓ ✓ ✓
Auto height ✓ ✓ ✓ ✓ ✓
Touch/drag ✓ ✓ ✓ ✓ ✓
Arrow keys ✓ ✓ ✓ ✓ ✓
Customize controls/nav ✓ ✓ ✓ ✓ ✓
Accessibility ✓ ✓ ✓ ✓ ✓
Respond to DOM visibility changes ✓ ✓ ✓ ✓ ✓
Custom events ✓ ✓ ✓ ✓ ✓
Nested ✓ ✓ ✓ ✓ ✓
* Default

top↑

Install

bower install tiny-slider or npm install tiny-slider

Usage

1. Add CSS (and IE8 polyfills if needed)

  1. ``` html
  2. <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/tiny-slider/2.9.4/tiny-slider.css">
  3. !--[if (lt IE 9)]><script src="https://cdnjs.cloudflare.com/ajax/libs/tiny-slider/2.9.4/min/tiny-slider.helper.ie8.js"></script>![endif]-->
  4. ```

2. Add markup

  1. ``` html
  2. <div class="my-slider">
  3.   <div></div>
  4.   <div></div>
  5.   <div></div>
  6. </div>
  8. ```

3. Call tns()

Option A: Add tiny-slider.js to your page:
  1. ``` html
  2. <script src="https://cdnjs.cloudflare.com/ajax/libs/tiny-slider/2.9.2/min/tiny-slider.js"></script>
  4. ```

Option B: Import tns via webpack or rollup:
  1. ``` js
  2. // yourScript.js
  3. import { tns } from "./node_modules/tiny-slider/src/tiny-slider"
  4. ```

Option C: Import tns directly start from v2.8.2
  1. ``` html
  2. <script type="module">
  3.   import {tns} from './src/tiny-slider.js';
  5.   var slider = tns({
  6.     container: '.my-slider',
  7.     items: 3,
  8.     slideBy: 'page',
  9.     autoplay: true
  10.   });
  11.   </script>
  12. ```
top↑

Options


OptionTypeDescription
---------
`container`NodeString
`mode`"carousel""gallery"
`axis`"horizontal""vertical"
`items`positiveDefault:
`gutter`positiveDefault:
`edgePadding`positiveDefault:
`fixedWidth`positivefalse
`autoWidth`BooleanDefault:
`viewportMax`positivefalse
`slideBy`positive"page"
`center`BooleanDefault:
`controls`BooleanDefault:
`controlsPosition`"top""bottom"
`controlsText`(TextMarkup)
`controlsContainer`NodeString
`prevButton`NodeString
`nextButton`NodeString
`nav`BooleanDefault:
`navPosition`"top""bottom"
`navContainer`NodeString
`navAsThumbnails`BooleanDefault:
`arrowKeys`BooleanDefault:
`speed`positiveDefault:
`autoplay`BooleanDefault:
`autoplayPosition`"top""bottom"
`autoplayTimeout`positiveDefault:
`autoplayDirection`"forward""backward"
`autoplayText`ArrayMarkup)
`autoplayHoverPause`BooleanDefault:
`autoplayButton`NodeString
`autoplayButtonOutput`BooleanDefault:
`autoplayResetOnVisibility`BooleanDefault:
`animateIn`StringDefault:
`animateOut`StringDefault:
`animateNormal`StringDefault:
`animateDelay`positivefalse
`loop`BooleanDefault:
`rewind`BooleanDefault:
`autoHeight`BooleanDefault:
`responsive`Object:false
`lazyload`BooleanDefault:
`lazyloadSelector`StringDefault:
`touch`BooleanDefault:
`mouseDrag`BooleanDefault:
`swipeAngle`positiveBoolean
`preventActionWhenRunning`BooleanDefault:
`preventScrollOnTouch`"auto""force"
`nested`"inner""outer"
`freezable`BooleanDefault:
`disable`BooleanDefault:
`startIndex`positiveDefault:
`onInit`Functionfalse
`useLocalStorage`BooleanDefault:
`nonce`|Default:

NOTE:
Prior to v2.0.2, options "container", "controlsContainer", "navContainer" and "autoplayButton" still need to be DOM elements.
E.g. container: document.querySelector('.my-slider')

top↑

Responsive options

The following options can be redefined in responsive field:
startIndex,
items,
slideBy,
speed,
autoHeight,
fixedWidth,
edgePadding,
gutter,
center,
controls,
controlsText,
nav,
autoplay,
autoplayHoverPause,
autoplayResetOnVisibility,
autoplayText,
autoplayTimeout,
touch,
mouseDrag,
arrowKeys,
disable
  1. ``` js
  2. <script>
  3.   var slider = tns({
  4.     container: '.my-slider',
  5.     items: 1,
  6.     responsive: {
  7.       640: {
  8.         edgePadding: 20,
  9.         gutter: 20,
  10.         items: 2
  11.       },
  12.       700: {
  13.         gutter: 30
  14.       },
  15.       900: {
  16.         items: 3
  17.       }
  18.     }
  19.   });
  20. </script>
  21. ```
NOTE:
+ The breakpoints behave like (min-width: breakpoint) in CSS, so an undefined option will be inherited from previous small breakpoints.
+ fixedWidth can only be changed to other positive integers. It can't be changed to negative integer, 0 or other data type.
top↑

Methods

The slider returns a slider object with some properties and methods once it's initialized:
  1. ``` js
  2. {
  3.   version: version, // tiny-slider version
  4.   getInfo: info(),
  5.   events: events, // Object
  6.   goTo: goTo(),
  7.   play: play(),
  8.   pause: pause(),
  9.   isOn: isOn, // Boolean
  10.   updateSliderHeight: updateInnerWrapperHeight(),
  11.   refresh: initSliderTransform(),
  12.   destroy: destroy(),
  13.   rebuild: rebuild()
  14. }
  15. ```
To get the slider information, you can either use the getInfo() method or subscribe to an Event. Both return an Object:
  1. ``` js
  2. {
  3.                 container: container, // slider container
  4.                slideItems: slideItems, // slides list
  5.              navContainer: navContainer, // nav container
  6.                  navItems: navItems, // dots list
  7.         controlsContainer: controlsContainer, // controls container
  8.               hasControls: hasControls, // indicate if controls exist
  9.                prevButton: prevButton, // previous button
  10.                nextButton: nextButton, // next button
  11.                     items: items, // items on a page
  12.                   slideBy: slideBy // items slide by
  13.                cloneCount: cloneCount, // cloned slide count
  14.                slideCount: slideCount, // original slide count
  15.             slideCountNew: slideCountNew, // total slide count after initialization
  16.                     index: index, // current index
  17.               indexCached: indexCached, // previous index
  18.              displayIndex: getCurrentSlide(), // display index starts from 1
  19.                navCurrent: navCurrent, // current dot index
  20.          navCurrentCached: navCurrentCached, // previous dot index
  21.                     pages: pages, // visible nav indexes
  22.               pagesCached: pagesCached,
  23.                     sheet: sheet,
  24.                     event: e || {}, // event object if available
  25. };
  26. ```

getInfo

Get slider information.
  1. ``` js
  2. slider.getInfo();

  4. document.querySelector('.next-button').onclick = function () {
  5.   // get slider info
  6.   var info = slider.getInfo(),
  7.       indexPrev = info.indexCached,
  8.       indexCurrent = info.index;

  10.   // update style based on index
  11.   info.slideItems[indexPrev].classList.remove('active');
  12.   info.slideItems[indexCurrent].classList.add('active');
  13. };
  14. ```

goTo

Go to specific slide by number or keywords.
  1. ``` js
  2. slider.goTo(3);
  3. slider.goTo('prev');
  4. slider.goTo('next');
  5. slider.goTo('first');
  6. slider.goTo('last');

  8. document.querySelector('.goto-button').onclick = function () {
  9.   slider.goTo(3);
  10. };
  11. ```

play

Programmatically start slider autoplay when autoplay: true.
  1. ``` js
  2. slider.play();
  3. ```

pause

Programmatically stop slider autoplay when autoplay: true.
  1. ``` js
  2. slider.pause();
  3. ```

updateSliderHeight

Manually adjust slider height when autoHeight is true.
  1. ``` js
  2. slider.updateSliderHeight();
  3. ```

destroy

Destroy the slider.
  1. ``` js
  2. slider.destroy();
  3. ```

rebuild

Rebuild the slider after destroy.
  1. ``` js
  2. slider = slider.rebuild();
  3. // this method returns a new slider Object with the same options with the original slider
  4. ```

Custom Events

Available events include: indexChanged, transitionStart, transitionEnd, newBreakpointStart, newBreakpointEnd, touchStart, touchMove, touchEnd, dragStart, dragMove and dragEnd.
  1. ``` js
  2. var customizedFunction = function (info, eventName) {
  3.   // direct access to info object
  4.   console.log(info.event.type, info.container.id);
  5. }

  7. // bind function to event
  8. slider.events.on('transitionEnd', customizedFunction);

  10. // remove function binding
  11. slider.events.off('transitionEnd', customizedFunction);
  12. ```
top↑

Fallback

  1. ```css
  2. .no-js .your-slider { overflow-x: auto; }
  3. .no-js .your-slider > div { float: none; }
  4. ```

Browser Support

Desktop:
Firefox 8+ ✓
Chrome 15+ ✓  (Should works on _Chrome 4-14_ as well, but I couldn't test it.)
Safari 4+ ✓
Opera 12.1+ ✓
IE 8+ ✓

Mobile:
Android Browser 4.2+ ✓
Chrome Mobile 63+ ✓
Firefox Mobile 28+ ✓
Maxthon 4+ ✓

Support

Browser Stack
Live tests and Automated Tests
Cross Browser Testing
Live tests, Screenshots and Automated Tests

Cdnjs

Images on demo page are from https://unsplash.com/.

License

This project is available under the MIT license.