DOCSEARCHbyAlgolia
Submit Docs

bxSlider Documentation

repository·master·Indexed 26 days ago

https://github.com/stevenwanderski/bxslider-4

A touch-enabled, responsive jQuery plugin for creating carousels and sliders. Version 4.2.17 supports horizontal, vertical, and fade modes for displaying images, video, or HTML content. Includes detailed configuration for pager and control options, auto and carousel modes, public methods, and event callbacks.

Tokens
2.5K
Snippets
6
Records
12
Agent score
38%

What's inside bxSlider

  1. Build bxSlider from source using Gulp

    master

    If you are developing on the bxSlider source code, you can use Gulp to compile and optimize assets. Ensure you have Node.js installed, then install Gulp globally and install the project dependencies.

    1. Install Gulp globally: npm install -g gulp
    2. Run npm install in the project directory.
    3. Use the available Gulp commands to build specific assets.
    npm install -g gulp
npm install

  2. Set up local development with Gulp

    master

    To build the project locally using Gulp, ensure you have Node.js installed, then run the following commands:

    1. Install the Gulp CLI globally: npm install --global gulp-cli
    2. Install local development tools: npm install
    3. Build the project: gulp
    npm install --global gulp-cli
npm install
gulp

  4. Create HTML markup for bxSlider

    master

    To prepare your content for the slider, create a <ul> element with the class bxslider. Each slide should be contained within a <li> element. These list items 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>

  5. Install bxSlider via CDN

    master

    To use bxSlider, you must include the jQuery library, the bxSlider JavaScript file, and the bxSlider CSS file. You can use the following CDN links to include these resources directly in your project.

    <!-- bxSlider Javascript file -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/bxslider/4.2.17/jquery.bxslider.min.js"></script>
<!-- bxSlider CSS file -->
<link href="https://cdnjs.cloudflare.com/ajax/libs/bxslider/4.2.17/jquery.bxslider.min.css" rel="stylesheet" />

  6. Configure Controls options

    master

    Use these options to customize the Next/Prev and Start/Stop buttons:

    • controls: Enable/disable Next/Prev controls (default: true).
    • nextText: Text for the 'Next' control (default: 'Next').
    • prevText: Text for the 'Prev' control (default: 'Prev').
    • nextSelector: jQuery selector for the 'Next' control (default: null).
    • prevSelector: jQuery selector for the 'Prev' control (default: null).
    • autoControls: Enable/disable Start/Stop controls (default: false).
    • startText: Text for the 'Start' control (default: 'Start').
    • stopText: Text for the 'Stop' control (default: 'Stop').
    • autoControlsCombine: If true, only shows 'Stop' when playing and 'Start' when paused (default: false).
    • autoControlsSelector: jQuery selector for the auto controls (default: null).
    • keyboardEnabled: Enable keyboard navigation (default: false).

  7. Configure General bxSlider options

    master

    The following options control the core behavior and appearance of the slider:

    • mode: Transition type. Options: 'horizontal' (default), 'vertical', 'fade'.
    • speed: Transition duration in ms (default: 500).
    • slideMargin: Margin between slides in pixels (default: 0).
    • startSlide: Zero-based index of the starting slide (default: 0).
    • randomStart: If true, starts on a random slide (default: false).
    • slideSelector: jQuery selector for specific slide elements. If empty, uses all immediate children (default: '').
    • infiniteLoop: If true, loops from last to first slide and vice-versa (default: true).
    • hideControlOnEnd: If true, adds disabled class to controls when infiniteLoop is false (default: false).
    • easing: CSS transition timing function (e.g., 'linear', 'ease', 'ease-in-out') or jQuery easing name (default: null).
    • captions: If true, uses image title attributes as captions (default: false).
    • ticker: Enables news-ticker mode (default: false).
    • tickerHover: Pauses ticker on hover (Note: does not work with CSS transitions) (default: false).
    • adaptiveHeight: Dynamically adjusts slider height to match slide height (default: false).
    • adaptiveHeightSpeed: Duration of height transition in ms (default: 500).
    • video: Set to true if slides contain video; requires plugins/jquery.fitvids.js (default: false).
    • responsive: Enables/disables auto-resize (default: true).
    • useCSS: Uses CSS transitions for hardware acceleration if true (default: true).
    • preloadImages: 'all' (all images), 'visible' (only initial slides), or 'none' (default: 'visible').
    • touchEnabled: Enables touch swipe transitions (default: true).
    • swipeThreshold: Pixels required for a swipe to trigger transition (default: 50).
    • oneToOneTouch: If true, non-fade slides follow finger during swipe (default: true).
    • preventDefaultSwipeX: Prevents x-axis movement on touch screen (default: true).
    • preventDefaultSwipeY: Prevents y-axis movement on touch screen (default: false).
    • wrapperClass: Custom class for the slider wrapper (default: 'bx-wrapper').

  8. Configure Auto and Carousel options

    master

    Auto Mode

    • auto: Enable automatic transitions (default: false).
    • stopAutoOnClick: Stop auto mode on control interaction (default: false).
    • pause: Time between auto transitions in ms (default: 4000).
    • autoStart: Start playing on load (default: true).
    • autoDirection: Direction of auto transitions: 'next' or 'prev' (default: 'next').
    • autoHover: Pause auto mode on mouse hover (default: false).
    • autoDelay: Delay before auto mode starts in ms (default: 0).

    Carousel Mode

    • minSlides: Minimum number of slides to show (default: 1).
    • maxSlides: Maximum number of slides to show (default: 1).
    • moveSlides: Number of slides to move on transition. Must be >= minSlides and <= maxSlides. If 0, uses number of fully-visible slides (default: 0).
    • slideWidth: Width of each slide. Required for all horizontal carousels! (default: 0).
    • shrinkItems: If true, shrinks images to fit viewport based on min/max slides (default: false).

  9. Configure Pager options

    master

    Use these options to customize the pager (navigation dots/numbers):

    • pager: Enable/disable pager (default: true).
    • pagerType: 'full' (individual links) or 'short' (e.g., '1 / 5') (default: 'full').
    • pagerShortSeparator: Character used for 'short' pager type (default: ' / ').
    • pagerSelector: jQuery selector for the element used to populate the pager (default: '').
    • pagerCustom: Parent element for the pager. Must contain <a data-slide-index="x"> for each slide (default: null).
    • buildPager: A function called on every slide element; the returned value is used as the pager item markup (default: null).

  10. Use bxSlider Public Methods

    master

    Once a slider is initialized, you can control it using these methods on the returned jQuery object:

    • goToSlide(index): Transition to the specified zero-based index.
    • goToNextSlide(): Perform a 'Next' transition.
    • goToPrevSlide(): Perform a 'Prev' transition.
    • startAuto(preventUpdate): Start the auto show. Pass false to prevent auto control updates.
    • stopAuto(preventUpdate): Stop the auto show. Pass false to prevent auto control updates.
    • getCurrentSlide(): Returns the current active slide.
    • getSlideCount(): Returns the total number of slides.
    • redrawSlider(): Redraw the slider (useful when unhiding a slider).
    • reloadSlider(settings): Reload the slider with optional new settings (useful for adding slides on the fly).
    • destroySlider(): Reverts all slider elements to their original state.
    // Example usage of public methods
var slider = $('.bxslider').bxSlider();

slider.goToSlide(3);
slider.goToNextSlide();
slider.goToPrevSlide();
slider.startAuto();
slider.stopAuto();

var current = slider.getCurrentSlide();
var slideQty = slider.getSlideCount();

slider.redrawSlider();
slider.reloadSlider();
slider.destroySlider();

  11. Use bxSlider Callbacks

    master

    Callbacks allow you to execute code during specific slider events. Most callbacks receive arguments related to the slide index or element.

    • onSliderLoad: Executes after the slider is fully loaded. (currentIndex)
    • onSliderResize: Executes after the slider is resized. (currentIndex)
    • onSlideBefore: Executes immediately before a transition. ($slideElement, oldIndex, newIndex)
    • onSlideAfter: Executes immediately after a transition. ($slideElement, oldIndex, newIndex)
    • onSlideNext: Executes immediately before a 'Next' transition. ($slideElement, oldIndex, newIndex)
    • onSlidePrev: Executes immediately before a 'Prev' transition. ($slideElement, oldIndex, newIndex)
    • onAutoChange: Executes after an auto transition starts or stops. (state) where state is a boolean.

  12. Reference Gulp build commands

    master

    The following Gulp commands are available for local development and asset compilation:

    • gulp: Compile and optimize all files to the dist folder.
    • gulp styles: Compile CSS assets only to dist.
    • gulp scripts: Compile JavaScript assets only to dist.
    • gulp images: Run lossless compression on all images and copy them to dist.
    • gulp jshint: Checks JS and JSON code for errors based on .jshintrc settings.
    gulp
gulp styles
gulp scripts
gulp images
gulp jshint