Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Responsive jQuery content slider
JavaScript CSS

This branch is 146 commits behind master

readme.md

Introducing bxSlider 4.0

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

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: all  
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.

Something went wrong with that request. Please try again.