383366063 / bxslider-4

Responsive jQuery content slider

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

New in 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.

###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 WTFPL license - http://sam.zoy.org/wtfpl/

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, "Next" control will be hidden on last slide and vice-versa
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)

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)

###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

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();  

Long live Zep.