/bxslider-4

Responsive jQuery content slider

Primary LanguageJavaScript

#bxSlider 4.1.2 ##The fully-loaded, responsive jQuery content slider

###Why should I use this slider?

  • Fully responsive - will adapt to any device
  • Horizontal, vertical, and fade modes
  • Slides can contain images, video, or HTML content
  • Full callback API and public methods
  • Small file size, fully themed, simple to implement
  • Browser support: Firefox, Chrome, Safari, iOS, Android, IE7+
  • Tons of configuration options

For complete documentation, tons of examples, and a good time, visit:

http://bxslider.com

Written by: Steven Wanderski - http://stevenwanderski.com

###License Released under the MIT license - http://opensource.org/licenses/MIT

Let's get on with it!

##Installation

###Step 1: Link required files

First and most important, the jQuery library needs to be included (no need to download - link directly from Google). Next, download the package from this site and link the bxSlider CSS file (for the theme) and the bxSlider Javascript file.

<!-- jQuery library (served from Google) -->
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.8.2/jquery.min.js"></script>
<!-- bxSlider Javascript file -->
<script src="/js/jquery.bxslider.min.js"></script>
<!-- bxSlider CSS file -->
<link href="/lib/jquery.bxslider.css" rel="stylesheet" />

###Step 2: Create HTML markup

Create a <ul class="bxslider"> element, with a <li> for each slide. Slides can contain images, video, or any other HTML content!

<ul class="bxslider">
  <li><img src="/images/pic1.jpg" /></li>
  <li><img src="/images/pic2.jpg" /></li>
  <li><img src="/images/pic3.jpg" /></li>
  <li><img src="/images/pic4.jpg" /></li>
</ul>

###Step 3: Call the bxSlider

Call .bxslider() on <ul class="bxslider">. Note that the call must be made inside of a $(document).ready() call, or the plugin will not work!

$(document).ready(function(){
  $('.bxslider').bxSlider();
});

##Configuration options

###General

mode Type of transition between slides

default: 'horizontal'
options: 'horizontal', 'vertical', 'fade'

speed Slide transition duration (in ms)

default: 500
options: integer

slideMargin Margin between each slide

default: 0
options: integer

startSlide Starting slide index (zero-based)

default: 0
options: integer

randomStart Start slider on a random slide

default: false
options: boolean (true / false)

slideSelector Element to use as slides (ex. 'div.slide').
Note: by default, bxSlider will use all immediate children of the slider element

default: ''
options: jQuery selector

infiniteLoop If true, clicking "Next" while on the last slide will transition to the first slide and vice-versa

default: true
options: boolean (true / false)

hideControlOnEnd If true, "Prev" and "Next" controls will receive a class disabled when slide is the first or the last
Note: Only used when infiniteLoop: false

default: false
options: boolean (true / false)

easing The type of "easing" to use during transitions. If using CSS transitions, include a value for the transition-timing-function property. If not using CSS transitions, you may include plugins/jquery.easing.1.3.js for many options.
See http://gsgd.co.uk/sandbox/jquery/easing/ for more info.

default: null
options: if using CSS: 'linear', 'ease', 'ease-in', 'ease-out', 'ease-in-out', 'cubic-bezier(n,n,n,n)'. If not using CSS: 'swing', 'linear' (see the above file for more options)

captions Include image captions. Captions are derived from the image's title attribute

default: false
options: boolean (true / false)

ticker Use slider in ticker mode (similar to a news ticker)

default: false
options: boolean (true / false)

tickerHover Ticker will pause when mouse hovers over slider. Note: this functionality does NOT work if using CSS transitions!

default: false
options: boolean (true / false)

adaptiveHeight Dynamically adjust slider height based on each slide's height

default: false
options: boolean (true / false)

adaptiveHeightSpeed Slide height transition duration (in ms). Note: only used if adaptiveHeight: true

default: 500
options: integer

video If any slides contain video, set this to true. Also, include plugins/jquery.fitvids.js
See http://fitvidsjs.com/ for more info

default: false
options: boolean (true / false)

responsive Enable or disable auto resize of the slider. Useful if you need to use fixed width sliders.

default: true
options: boolean (true /false)

useCSS If true, CSS transitions will be used for horizontal and vertical slide animations (this uses native hardware acceleration). If false, jQuery animate() will be used.

default: true
options: boolean (true / false)

preloadImages If 'all', preloads all images before starting the slider. If 'visible', preloads only images in the initially visible slides before starting the slider (tip: use 'visible' if all slides are identical dimensions)

default: 'visible'
options: 'all', 'visible'

touchEnabled If true, slider will allow touch swipe transitions

default: true
options: boolean (true / false)

swipeThreshold Amount of pixels a touch swipe needs to exceed in order to execute a slide transition. Note: only used if touchEnabled: true

default: 50
options: integer

oneToOneTouch If true, non-fade slides follow the finger as it swipes

default: true
options: boolean (true / false)

preventDefaultSwipeX If true, touch screen will not move along the x-axis as the finger swipes

default: true
options: boolean (true / false)

preventDefaultSwipeY If true, touch screen will not move along the y-axis as the finger swipes

default: false
options: boolean (true / false)

wrapperClass Class to wrap the slider in. Change to prevent from using default bxSlider styles.

default: 'bx-wrapper'
options: string

###Pager

pager If true, a pager will be added

default: true
options: boolean (true / false)

pagerType If 'full', a pager link will be generated for each slide. If 'short', a x / y pager will be used (ex. 1 / 5)

default: 'full'
options: 'full', 'short'

pagerShortSeparator If pagerType: 'short', pager will use this value as the separating character

default: ' / '
options: string

pagerSelector Element used to populate the populate the pager. By default, the pager is appended to the bx-viewport

default: ''
options: jQuery selector

pagerCustom Parent element to be used as the pager. Parent element must contain a <a data-slide-index="x"> element for each slide. See example here. Not for use with dynamic carousels.

default: null
options: jQuery selector

buildPager If supplied, function is called on every slide element, and the returned value is used as the pager item markup.
See examples for detailed implementation

default: null
options: function(slideIndex)

###Controls

controls If true, "Next" / "Prev" controls will be added

default: true
options: boolean (true / false)

nextText Text to be used for the "Next" control

default: 'Next'
options: string

prevText Text to be used for the "Prev" control

default: 'Prev'
options: string

nextSelector Element used to populate the "Next" control

default: null
options: jQuery selector

prevSelector Element used to populate the "Prev" control

default: null
options: jQuery selector

autoControls If true, "Start" / "Stop" controls will be added

default: false
options: boolean (true / false)

startText Text to be used for the "Start" control

default: 'Start'
options: string

stopText Text to be used for the "Stop" control

default: 'Stop'
options: string

autoControlsCombine When slideshow is playing only "Stop" control is displayed and vice-versa

default: false
options: boolean (true / false)

autoControlsSelector Element used to populate the auto controls

default: null
options: jQuery selector

###Auto

auto Slides will automatically transition

default: false
options: boolean (true / false)

pause The amount of time (in ms) between each auto transition

default: 4000
options: integer

autoStart Auto show starts playing on load. If false, slideshow will start when the "Start" control is clicked

default: true
options: boolean (true / false)

autoDirection The direction of auto show slide transitions

default: 'next'
options: 'next', 'prev'

autoHover Auto show will pause when mouse hovers over slider

default: false
options: boolean (true / false)

autoDelay Time (in ms) auto show should wait before starting

default: 0
options: integer

###Carousel

minSlides The minimum number of slides to be shown. Slides will be sized down if carousel becomes smaller than the original size.

default: 1
options: integer

maxSlides The maximum number of slides to be shown. Slides will be sized up if carousel becomes larger than the original size.

default: 1
options: integer

moveSlides The number of slides to move on transition. This value must be >= minSlides, and <= maxSlides. If zero (default), the number of fully-visible slides will be used.

default: 0
options: integer

slideWidth The width of each slide. This setting is required for all horizontal carousels!

default: 0
options: integer

###Callbacks

onSliderLoad Executes immediately after the slider is fully loaded

default: function(){}
options: function(currentIndex){ // your code here }
arguments:
  currentIndex: element index of the current slide

onSliderResize Executes immediately after the slider is resized

default: function(){}
options: function(currentIndex){ // your code here }
arguments:
  currentIndex: element index of the current slide

onSlideBefore Executes immediately before each slide transition.

default: function(){}
options: function($slideElement, oldIndex, newIndex){ // your code here }
arguments:
  $slideElement: jQuery element of the destination element
  oldIndex: element index of the previous slide (before the transition)
  newIndex: element index of the destination slide (after the transition)

onSlideAfter Executes immediately after each slide transition. Function argument is the current slide element (when transition completes).

default: function(){}
options: function($slideElement, oldIndex, newIndex){ // your code here }
arguments:
  $slideElement: jQuery element of the destination element
  oldIndex: element index of the previous slide (before the transition)
  newIndex: element index of the destination slide (after the transition)

onSlideNext Executes immediately before each "Next" slide transition. Function argument is the target (next) slide element.

default: function(){}
options: function($slideElement, oldIndex, newIndex){ // your code here }
arguments:
  $slideElement: jQuery element of the destination element
  oldIndex: element index of the previous slide (before the transition)
  newIndex: element index of the destination slide (after the transition)

onSlidePrev Executes immediately before each "Prev" slide transition. Function argument is the target (prev) slide element.

default: function(){}
options: function($slideElement, oldIndex, newIndex){ // your code here }
arguments:
  $slideElement: jQuery element of the destination element
  oldIndex: element index of the previous slide (before the transition)
  newIndex: element index of the destination slide (after the transition)

###Public methods

goToSlide Performs a slide transition to the supplied slide index (zero-based)

example:
slider = $('.bxslider').bxSlider();
slider.goToSlide(3);

goToNextSlide Performs a "Next" slide transition

example:
slider = $('.bxslider').bxSlider();
slider.goToNextSlide();

goToPrevSlide Performs a "Prev" slide transition

example:
slider = $('.bxslider').bxSlider();
slider.goToPrevSlide();

startAuto Starts the auto show. Provide an argument false to prevent the auto controls from being updated.

example:
slider = $('.bxslider').bxSlider();
slider.startAuto();

stopAuto Stops the auto show. Provide an argument false to prevent the auto controls from being updated.

example:
slider = $('.bxslider').bxSlider();
slider.stopAuto();

getCurrentSlide Returns the current active slide

example:
slider = $('.bxslider').bxSlider();
var current = slider.getCurrentSlide();

getSlideCount Returns the total number of slides in the slider

example:
slider = $('.bxslider').bxSlider();
var slideQty = slider.getSlideCount();

reloadSlider Reload the slider. Useful when adding slides on the fly. Accepts an optional settings object. See here for an example.

example:
slider = $('.bxslider').bxSlider();
slider.reloadSlider();

destroySlider Destroy the slider. This reverts all slider elements back to their original state (before calling the slider).

example:
slider = $('.bxslider').bxSlider();
slider.destroySlider();

Changelog

Version 4.1.2

  • Added bower.json configuration file. Manage bxSlider as a dependency using bower.

Version 4.1.1

  • Removed imagesLoaded library and added iframe preloading support
  • Added responsive option - setting to false will prevent $(window).resize binding

Version 4.1

  • Carousel mode (minSlides / maxSlides) was re-written to be more intuitive.
  • SlideWidth now acts as it should (slides respect the width value).
  • SlideWidth now properly parsed: accepts string ("600px") or integer (600).
  • Slider now only needs to load visible slides (by default) in order to initialize which results in much faster loading. A "preloadImages" setting allows for configuration.

Long live Zep.