fluid-slider
v1.0.4
Published
Lightweight Slider library with support for mobile devices with touch gestures (swipe left/right), navigation buttons and slider count bullets.
Downloads
17
Maintainers
Readme
Fluid Slider
Provide functions to handle animations and transitions gracefully. Execute a function before or after playing a css animation on an element.
Installation
Setting up is pretty straight-forward. Download the js and css files from dist folder and include them in your HTML, you'll also need the library Hammer.JS:
<link rel='stylesheet' id='fluid-slider' href='dist/fluid-slider.min.css' type='text/css' media='all' />
<script type="text/javascript" src="https://hammerjs.github.io/dist/hammer.min.js"></script>
<script type="text/javascript" src="path/to/dist/fluid-slider.min.js"></script>
NPM
Fluid Slider is also available on NPM:
$ npm install fluid-slider
When using NPM, Hammer.JS will be added as a dependency.
Initialization
Once the Fluid Slider script is loaded all functions will be available through the global variable window.FluidSlider
, however to enable the slider components you need to call the function init
:
Call the function FluidSlider.init( options );
passing the options
parameter as an object.
Options Available
The options
parameter accept any of the available options from the default settings by passing the new values as an object. You can simply ommit the options you don't want to change the default values of.
These are the currently accepted options with their default values, if in doubt check the source code:
var _defaults = {
sliderWrapperSelector: '.slider-wrapper',
sliderViewportSelector: '.slider-viewport',
sliderContainerSelector: '.slider-container',
sliderItemSelector: '.slider-item',
isActivatedClass: 'is-activated',
isDisabledClass: 'is-disabled',
isResizingClass: 'is-resizing',
isAnimatingClass: 'is-animating',
isCurrentClass: 'is-current',
slideSpacing: 0, // px
slideSensitivity: 30, // % of slide item width
touchEventsSensitivity: 25, // px
slidesPerViewAttribute: 'data-slider-per-view',
slidesPerView: {
xs: { breakpointInitial: 0, breakpointFinal: 749, itemsPerView: 1 },
md: { breakpointInitial: 750, breakpointFinal: 999, itemsPerView: 1 },
ml: { breakpointInitial: 1000, breakpointFinal: 1199, itemsPerView: 1 },
lg: { breakpointInitial: 1200, breakpointFinal: 1499, itemsPerView: 1 },
xl: { breakpointInitial: 1500, breakpointFinal: 100000, itemsPerView: 1 }, // breakpointFinal can be any very high number
},
createNavigationButtons: false,
createNavigationButtonsAttribute: 'data-slider-navigation-buttons',
navigationButtonsSelector: '.slider-navigation',
navigationPrevSelector: '.slider-navigation__prev',
navigationNextSelector: '.slider-navigation__next',
hasNavigationButtonsClass: 'has-navigation-buttons',
navigationButtonsTemplate: '<div class="slider-navigation"><button class="slider-navigation__prev">Previous</button></div><button class="slider-navigation__next">Next</button></div>',
createNavigationBullets: false,
createNavigationBulletsAttribute: 'data-slider-navigation-bullets',
navigationBulletsSelector: '.slider-navigation-bullets',
navigationBulletItemSelector: '.slider-navigation-bullets__item',
hasNavigationBulletsClass: 'has-navigation-bullets',
navigationBulletsWrapperTemplate: '<div class="slider-navigation-bullets"></div>',
navigationBulletItemTemplate: '<span class="slider-navigation-bullets__item"></span>',
};
For example, if you want to enable the creation of navigation buttons and bullets for every Slider in your page (setting the default options for your project), initialize the component with the options below:
var options = {
createNavigationButtons: true,
createNavigationBullets: true,
}
FluidSlider.init( options );
Everything else will use the default values.
Basic Usage
1. Required HTML elements structure
The slider component requires the following HTML elements structure:
<div class="slider-wrapper">
<div class="slider-viewport">
<div class="slider-container">
<div class="slider-item"> Slider 1 </div>
<div class="slider-item"> Slider 2 </div>
<div class="slider-item"> Slider 3 </div>
<div class="slider-item"> Slider 4 </div>
<div class="slider-item"> Slider 5 </div>
<div class="slider-item"> Slider 6 </div>
</div>
</div>
</div>
The elements for the navigation buttons and bullets are added during runtime. You can specify the HTML template to be used for these elements by changing the related options:
var options = {
navigationButtonsTemplate: '<your_navigation_buttons__html_template>',
navigationBulletsWrapperTemplate: '<your_navigation_bullet__html_template>',
navigationBulletItemTemplate: '<your_navigation_bullet_item__html_template>',
}
FluidSlider.init( options );
The HTML templates are useful to change not only the markup of the elements, for instance to add a specific class used in your project, but also to change the labels of these buttons to a translated text.
2. Using data
attributes to change slider properties
Another way to change the behavior of a slider component is to add data attributes to specific elements, this is useful if you want to change the properties of one instance of the slider component but keep the other instances with the default options.
Again, to enable the creation of navigation buttons and bullets, but this time for only one instance of the slider component, supposing Fluid Slider was initialized with its default options:
<div class="slider-wrapper" data-slider-navigation-buttons="true" data-slider-navigation-bullets="true">
<div class="slider-viewport">
<div class="slider-container">
<div class="slider-item"> Slider 1 </div>
<div class="slider-item"> Slider 2 </div>
<div class="slider-item"> Slider 3 </div>
<div class="slider-item"> Slider 4 </div>
<div class="slider-item"> Slider 5 </div>
<div class="slider-item"> Slider 6 </div>
</div>
</div>
</div>
Not all options can be set with data
attributes, these are the available properties that can be set with data
attributes:
data-slider-per-view
: used to set the value of the optionslidesPerView
, an JSON string is expected with the structure similar to the option default value.data-slider-navigation-buttons
: used to set the value of the optioncreateNavigationButtons
, valid values aretrue
orfalse
.data-slider-navigation-bullets
: used to set the value of the optioncreateNavigationBullets
, valid values aretrue
orfalse
.
Contributing to Development
This isn't a large project by any means, but you are definitely welcome to contribute.
Development environment
Clone the repo and run npm install:
$ cd path/to/fluid-slider
$ npm install
Run the build command:
$ gulp build
Build on file save:
$ gulp
$ gulp watch
License
Licensed under MIT.