bxSlider (stevenwanderski/bxslider-4)

bxSlider

https://github.com/stevenwanderski/bxslider-4
Admin
bxSlider is a fully responsive jQuery plugin for creating carousels and content sliders with support...

Tokens:21,341
Snippets:196
Trust Score:7.5
Update:6 days ago
Show doc for...
Context Summary (auto-generated)
Raw
# bxSlider

bxSlider is a fully-featured, responsive jQuery content slider plugin that enables developers to create carousels, image galleries, and content sliders with ease. It supports horizontal, vertical, and fade transition modes, and includes built-in touch/swipe support for mobile devices, making it ideal for creating responsive websites that work across all devices and screen sizes.

The plugin offers extensive customization through configuration options, callback functions, and public methods. It leverages CSS3 transitions for hardware-accelerated animations when available, falling back to jQuery animations for older browsers. bxSlider handles image preloading, adaptive heights, infinite looping, auto-play functionality, and provides full accessibility support with ARIA attributes.

## Installation

### Include Required Files

Include jQuery and bxSlider files in your HTML page to set up the slider with required dependencies.

```html
<!DOCTYPE html>
<html>
<head>
  <!-- jQuery library -->
  <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>

  <!-- bxSlider CSS (for theme) -->
  <link href="https://cdnjs.cloudflare.com/ajax/libs/bxslider/4.2.17/jquery.bxslider.min.css" rel="stylesheet" />

  <!-- bxSlider JavaScript -->
  <script src="https://cdnjs.cloudflare.com/ajax/libs/bxslider/4.2.17/jquery.bxslider.min.js"></script>
</head>
<body>
  <ul class="bxslider">
    <li><img src="/images/slide1.jpg" title="Caption for slide 1" /></li>
    <li><img src="/images/slide2.jpg" title="Caption for slide 2" /></li>
    <li><img src="/images/slide3.jpg" title="Caption for slide 3" /></li>
  </ul>

  <script>
    $(document).ready(function(){
      $('.bxslider').bxSlider();
    });
  </script>
</body>
</html>
```

## Basic Initialization

### bxSlider()

Initialize the slider on any container element. The plugin will use all immediate children as slides by default.

```javascript
$(document).ready(function(){
  // Basic initialization with default settings
  var slider = $('.bxslider').bxSlider();

  // Initialization with custom options
  var customSlider = $('.bxslider').bxSlider({
    mode: 'fade',
    speed: 800,
    pager: true,
    controls: true,
    auto: true,
    pause: 4000
  });
});
```

## Configuration Options

### Mode Options

Configure the transition mode between slides - horizontal sliding, vertical sliding, or crossfade effects.

```javascript
$('.bxslider').bxSlider({
  // Transition type: 'horizontal', 'vertical', or 'fade'
  mode: 'horizontal',

  // Transition speed in milliseconds
  speed: 500,

  // CSS easing for transitions
  // CSS: 'linear', 'ease', 'ease-in', 'ease-out', 'ease-in-out', 'cubic-bezier(n,n,n,n)'
  // jQuery: 'swing', 'linear'
  easing: 'ease-in-out',

  // Use CSS transitions for hardware acceleration (recommended)
  useCSS: true,

  // Starting slide index (zero-based)
  startSlide: 0,

  // Start on a random slide
  randomStart: false
});
```

### Loop and Navigation Options

Control infinite looping behavior and how controls appear at the first and last slides.

```javascript
$('.bxslider').bxSlider({
  // Enable infinite loop (seamless transition from last to first slide)
  infiniteLoop: true,

  // Hide prev/next controls when on first/last slide (only when infiniteLoop: false)
  hideControlOnEnd: false,

  // Margin between slides in pixels
  slideMargin: 10,

  // Custom jQuery selector for slides (default uses immediate children)
  slideSelector: 'div.slide'
});
```

### Pager Options

Configure the slide pager/indicator dots for navigation between slides.

```javascript
$('.bxslider').bxSlider({
  // Show pager navigation
  pager: true,

  // Pager type: 'full' (one dot per slide) or 'short' (1 / 5 format)
  pagerType: 'full',

  // Separator for short pager type
  pagerShortSeparator: ' / ',

  // Custom element to contain the pager
  pagerSelector: '#custom-pager',

  // Use custom pager (element must contain <a data-slide-index="x"> for each slide)
  pagerCustom: '#thumbnail-pager',

  // Custom function to build pager item markup
  buildPager: function(slideIndex) {
    // Return thumbnail images as pager
    return '<img src="/thumbs/thumb-' + (slideIndex + 1) + '.jpg" />';
  }
});
```

### Controls Options

Customize the previous/next navigation controls and their appearance.

```javascript
$('.bxslider').bxSlider({
  // Show prev/next controls
  controls: true,

  // Text for next button
  nextText: 'Next',

  // Text for prev button
  prevText: 'Prev',

  // Custom elements for controls
  nextSelector: '#slider-next',
  prevSelector: '#slider-prev',

  // Enable keyboard navigation (left/right arrow keys)
  keyboardEnabled: true
});
```

### Auto Play Options

Configure automatic slideshow functionality with timing and direction controls.

```javascript
$('.bxslider').bxSlider({
  // Enable automatic transitions
  auto: true,

  // Time between transitions in milliseconds
  pause: 4000,

  // Start auto show on load (false = start on "Start" button click)
  autoStart: true,

  // Direction of auto transitions: 'next' or 'prev'
  autoDirection: 'next',

  // Stop auto on user interaction with controls
  stopAutoOnClick: true,

  // Pause auto on mouse hover
  autoHover: true,

  // Delay before starting auto (in ms)
  autoDelay: 1000,

  // Show start/stop controls
  autoControls: true,

  // Text for start/stop buttons
  startText: 'Start',
  stopText: 'Stop',

  // Combine start/stop into single toggle button
  autoControlsCombine: true,

  // Custom element for auto controls
  autoControlsSelector: '#auto-controls'
});
```

### Carousel Options

Configure multi-slide carousels that display multiple items at once.

```javascript
$('.bxslider').bxSlider({
  // Minimum number of slides to show
  minSlides: 2,

  // Maximum number of slides to show
  maxSlides: 4,

  // Number of slides to move per transition
  // Must be >= minSlides and <= maxSlides
  // 0 = auto (uses number of fully visible slides)
  moveSlides: 1,

  // Width of each slide in pixels (REQUIRED for horizontal carousels)
  slideWidth: 300,

  // Shrink items to fit viewport based on maxSlides/minSlides
  shrinkItems: true,

  // Margin between carousel slides
  slideMargin: 10
});
```

### Touch and Swipe Options

Configure touch interaction for mobile devices.

```javascript
$('.bxslider').bxSlider({
  // Enable touch swipe transitions
  touchEnabled: true,

  // Minimum swipe distance to trigger slide change (in pixels)
  swipeThreshold: 50,

  // Slide follows finger as it swipes (non-fade modes only)
  oneToOneTouch: true,

  // Prevent page scroll on x-axis swipe
  preventDefaultSwipeX: true,

  // Prevent page scroll on y-axis swipe
  preventDefaultSwipeY: false
});
```

### Adaptive Height and Responsive Options

Configure responsive behavior and dynamic height adjustment.

```javascript
$('.bxslider').bxSlider({
  // Enable responsive resizing
  responsive: true,

  // Dynamically adjust height based on current slide
  adaptiveHeight: true,

  // Height transition speed in milliseconds
  adaptiveHeightSpeed: 500,

  // Image preloading: 'all', 'visible', or 'none'
  preloadImages: 'visible'
});
```

### Accessibility Options

Configure ARIA attributes for screen reader support.

```javascript
$('.bxslider').bxSlider({
  // Add aria-live attribute to slider viewport
  ariaLive: true,

  // Add aria-hidden to non-visible slides
  ariaHidden: true
});
```

### Additional Options

Configure captions, tickers, video support, and wrapper styling.

```javascript
$('.bxslider').bxSlider({
  // Show image captions (from img title attribute)
  captions: true,

  // Enable ticker mode (continuous scrolling like news ticker)
  ticker: false,

  // Pause ticker on hover (doesn't work with CSS transitions)
  tickerHover: false,

  // Enable video support (requires jquery.fitvids.js)
  video: true,

  // Custom wrapper class (change to use custom styles)
  wrapperClass: 'bx-wrapper'
});
```

## Public Methods

### goToSlide(index)

Navigate directly to a specific slide by its zero-based index.

```javascript
$(document).ready(function(){
  var slider = $('.bxslider').bxSlider();

  // Go to the 4th slide (index 3)
  slider.goToSlide(3);

  // Navigate via custom buttons
  $('#slide-1-btn').click(function() {
    slider.goToSlide(0);
  });

  $('#slide-2-btn').click(function() {
    slider.goToSlide(1);
  });
});
```

### goToNextSlide()

Transition to the next slide in the sequence.

```javascript
$(document).ready(function(){
  var slider = $('.bxslider').bxSlider({
    controls: false // Hide default controls
  });

  // Custom next button
  $('#custom-next').click(function(e) {
    e.preventDefault();
    slider.goToNextSlide();
  });
});
```

### goToPrevSlide()

Transition to the previous slide in the sequence.

```javascript
$(document).ready(function(){
  var slider = $('.bxslider').bxSlider({
    controls: false
  });

  // Custom previous button
  $('#custom-prev').click(function(e) {
    e.preventDefault();
    slider.goToPrevSlide();
  });
});
```

### startAuto() / stopAuto()

Control the automatic slideshow programmatically.

```javascript
$(document).ready(function(){
  var slider = $('.bxslider').bxSlider({
    auto: true,
    autoStart: false // Don't start automatically
  });

  // Start auto play
  $('#play-btn').click(function() {
    slider.startAuto();
  });

  // Stop auto play
  $('#pause-btn').click(function() {
    slider.stopAuto();
  });

  // Pass true to prevent auto control button update
  slider.startAuto(true);
  slider.stopAuto(true);
});
```

### getCurrentSlide()

Get the index of the currently active slide.

```javascript
$(document).ready(function(){
  var slider = $('.bxslider').bxSlider();

  // Get current slide index
  $('#show-current').click(function() {
    var currentIndex = slider.getCurrentSlide();
    console.log('Current slide: ' + currentIndex);
    alert('You are viewing slide #' + (currentIndex + 1));
  });
});
```

### getSlideCount()

Get the total number of slides in the slider.

```javascript
$(document).ready(function(){
  var slider = $('.bxslider').bxSlider();

  // Get total slide count
  var totalSlides = slider.getSlideCount();
  console.log('Total slides: ' + totalSlides);

  // Display slide counter
  $('#slide-counter').html('1 / ' + totalSlides);
});
```

### redrawSlider()

Redraw the slider. Useful when showing a previously hidden slider.

```javascript
$(document).ready(function(){
  var slider = $('.bxslider').bxSlider();

  // Show hidden slider and redraw
  $('#show-slider').click(function() {
    $('.slider-container').show();
    slider.redrawSlider();
  });

  // Redraw after tab switch
  $('a[data-toggle="tab"]').on('shown.bs.tab', function() {
    slider.redrawSlider();
  });
});
```

### reloadSlider()

Reload the slider with optional new settings. Useful when adding/removing slides dynamically.

```javascript
$(document).ready(function(){
  var slider = $('.bxslider').bxSlider({
    mode: 'horizontal'
  });

  // Reload with same settings
  $('#reload-btn').click(function() {
    slider.reloadSlider();
  });

  // Reload with new settings
  $('#change-mode').click(function() {
    slider.reloadSlider({
      mode: 'fade',
      speed: 1000
    });
  });

  // Add new slide and reload
  $('#add-slide').click(function() {
    $('.bxslider').append('<li><img src="/images/new-slide.jpg" /></li>');
    slider.reloadSlider();
  });
});
```

### destroySlider()

Destroy the slider instance and revert to original DOM state.

```javascript
$(document).ready(function(){
  var slider = $('.bxslider').bxSlider();

  // Destroy slider
  $('#destroy-btn').click(function() {
    slider.destroySlider();
  });

  // Destroy and reinitialize with different settings
  $('#reinit-btn').click(function() {
    slider.destroySlider();
    slider = $('.bxslider').bxSlider({
      mode: 'vertical',
      pager: false
    });
  });
});
```

## Callback Functions

### onSliderLoad

Execute code immediately after the slider is fully loaded and initialized.

```javascript
$('.bxslider').bxSlider({
  onSliderLoad: function(currentIndex) {
    console.log('Slider loaded. Current slide: ' + currentIndex);

    // Remove loading indicator
    $('.loading-spinner').hide();

    // Show the slider
    $('.bxslider').css('visibility', 'visible');

    // Initialize other components that depend on slider
    initializeThumbnails(currentIndex);
  }
});
```

### onSliderResize

Execute code when the slider is resized (typically on window resize).

```javascript
$('.bxslider').bxSlider({
  onSliderResize: function(currentIndex) {
    console.log('Slider resized. Current slide: ' + currentIndex);

    // Adjust related elements
    var newHeight = $('.bx-viewport').height();
    $('.sidebar').css('height', newHeight);
  }
});
```

### onSlideBefore

Execute code immediately before each slide transition. Return false to cancel the transition.

```javascript
$('.bxslider').bxSlider({
  onSlideBefore: function($slideElement, oldIndex, newIndex) {
    console.log('Transitioning from slide ' + oldIndex + ' to slide ' + newIndex);

    // Update external elements
    $('#slide-title').text($slideElement.find('img').attr('title'));

    // Pause video on previous slide
    $('.bxslider li').eq(oldIndex).find('video')[0]?.pause();

    // Cancel transition based on condition
    if (someCondition) {
      return false; // Prevents the slide transition
    }
  }
});
```

### onSlideAfter

Execute code immediately after each slide transition completes.

```javascript
$('.bxslider').bxSlider({
  onSlideAfter: function($slideElement, oldIndex, newIndex) {
    console.log('Transitioned to slide ' + newIndex);

    // Update progress indicator
    var totalSlides = $('.bxslider > li').length;
    var progress = ((newIndex + 1) / totalSlides) * 100;
    $('.progress-bar').css('width', progress + '%');

    // Auto-play video on current slide
    $slideElement.find('video')[0]?.play();

    // Lazy load next slide images
    var nextSlide = $('.bxslider li').eq(newIndex + 1);
    nextSlide.find('img[data-src]').each(function() {
      $(this).attr('src', $(this).data('src'));
    });
  }
});
```

### onSlideNext / onSlidePrev

Execute code when navigating specifically via next or previous. Return false to cancel.

```javascript
$('.bxslider').bxSlider({
  onSlideNext: function($slideElement, oldIndex, newIndex) {
    console.log('Going to NEXT slide: ' + newIndex);

    // Track forward navigation
    analytics.track('slider_next', { from: oldIndex, to: newIndex });

    // Prevent navigation past a certain slide
    if (newIndex > 5 && !userIsLoggedIn) {
      alert('Please log in to view more slides');
      return false;
    }
  },

  onSlidePrev: function($slideElement, oldIndex, newIndex) {
    console.log('Going to PREVIOUS slide: ' + newIndex);

    // Track backward navigation
    analytics.track('slider_prev', { from: oldIndex, to: newIndex });
  }
});
```

### onAutoChange

Execute code when auto-play starts or stops.

```javascript
$('.bxslider').bxSlider({
  auto: true,
  autoControls: true,
  onAutoChange: function(isPlaying) {
    if (isPlaying) {
      console.log('Auto slideshow started');
      $('#auto-status').text('Playing');
      $('#play-icon').hide();
      $('#pause-icon').show();
    } else {
      console.log('Auto slideshow stopped');
      $('#auto-status').text('Paused');
      $('#play-icon').show();
      $('#pause-icon').hide();
    }
  }
});
```

## Complete Examples

### Image Gallery with Thumbnails

Create a full-featured image gallery with thumbnail navigation.

```html
<ul class="bxslider" id="main-slider">
  <li><img src="/images/photo1.jpg" title="Photo 1" /></li>
  <li><img src="/images/photo2.jpg" title="Photo 2" /></li>
  <li><img src="/images/photo3.jpg" title="Photo 3" /></li>
  <li><img src="/images/photo4.jpg" title="Photo 4" /></li>
</ul>

<div id="bx-pager">
  <a data-slide-index="0" href=""><img src="/thumbs/thumb1.jpg" /></a>
  <a data-slide-index="1" href=""><img src="/thumbs/thumb2.jpg" /></a>
  <a data-slide-index="2" href=""><img src="/thumbs/thumb3.jpg" /></a>
  <a data-slide-index="3" href=""><img src="/thumbs/thumb4.jpg" /></a>
</div>

<script>
$(document).ready(function(){
  $('#main-slider').bxSlider({
    mode: 'fade',
    captions: true,
    pagerCustom: '#bx-pager',
    adaptiveHeight: true,
    onSliderLoad: function(currentIndex) {
      $('#bx-pager a').eq(currentIndex).addClass('active');
    },
    onSlideAfter: function($slideElement, oldIndex, newIndex) {
      $('#bx-pager a').removeClass('active');
      $('#bx-pager a').eq(newIndex).addClass('active');
    }
  });
});
</script>

<style>
#bx-pager a {
  opacity: 0.5;
  transition: opacity 0.3s;
}
#bx-pager a.active,
#bx-pager a:hover {
  opacity: 1;
}
#bx-pager img {
  width: 80px;
  height: 60px;
  object-fit: cover;
}
</style>
```

### Responsive Product Carousel

Create a multi-item carousel that adapts to screen size.

```html
<div class="product-carousel">
  <div class="slide"><img src="/products/product1.jpg" /><h3>Product 1</h3><p>$29.99</p></div>
  <div class="slide"><img src="/products/product2.jpg" /><h3>Product 2</h3><p>$39.99</p></div>
  <div class="slide"><img src="/products/product3.jpg" /><h3>Product 3</h3><p>$49.99</p></div>
  <div class="slide"><img src="/products/product4.jpg" /><h3>Product 4</h3><p>$59.99</p></div>
  <div class="slide"><img src="/products/product5.jpg" /><h3>Product 5</h3><p>$69.99</p></div>
  <div class="slide"><img src="/products/product6.jpg" /><h3>Product 6</h3><p>$79.99</p></div>
</div>

<script>
$(document).ready(function(){
  $('.product-carousel').bxSlider({
    slideSelector: 'div.slide',
    minSlides: 1,
    maxSlides: 4,
    slideWidth: 250,
    slideMargin: 20,
    moveSlides: 1,
    shrinkItems: true,
    pager: false,
    auto: true,
    autoHover: true,
    pause: 5000,
    infiniteLoop: true,
    touchEnabled: true,
    onSliderResize: function(currentIndex) {
      // Handle responsive behavior
      var viewportWidth = $(window).width();
      if (viewportWidth < 768) {
        // Mobile: show 1-2 slides
        console.log('Mobile view');
      } else if (viewportWidth < 1024) {
        // Tablet: show 2-3 slides
        console.log('Tablet view');
      } else {
        // Desktop: show 3-4 slides
        console.log('Desktop view');
      }
    }
  });
});
</script>
```

### Video Slider

Create a slider with video content support.

```html
<!-- Include FitVids.js for responsive videos -->
<script src="/js/jquery.fitvids.js"></script>

<ul class="video-slider">
  <li>
    <iframe src="https://www.youtube.com/embed/VIDEO_ID_1" frameborder="0" allowfullscreen></iframe>
  </li>
  <li>
    <iframe src="https://www.youtube.com/embed/VIDEO_ID_2" frameborder="0" allowfullscreen></iframe>
  </li>
  <li>
    <video controls>
      <source src="/videos/video1.mp4" type="video/mp4">
    </video>
  </li>
</ul>

<script>
$(document).ready(function(){
  $('.video-slider').bxSlider({
    video: true,
    mode: 'fade',
    speed: 600,
    pager: true,
    adaptiveHeight: true,
    useCSS: false, // Better compatibility with videos
    onSlideBefore: function($slideElement, oldIndex, newIndex) {
      // Pause all videos when transitioning
      $('.video-slider iframe').each(function() {
        var src = $(this).attr('src');
        $(this).attr('src', src); // Reset iframe to stop video
      });
      $('.video-slider video').each(function() {
        this.pause();
      });
    }
  });
});
</script>
```

### News Ticker

Create a continuously scrolling news ticker effect.

```html
<ul class="news-ticker">
  <li>Breaking: Important news headline #1</li>
  <li>Update: Latest developments on story #2</li>
  <li>Alert: New information about topic #3</li>
  <li>Report: Coverage of event #4</li>
</ul>

<script>
$(document).ready(function(){
  $('.news-ticker').bxSlider({
    mode: 'horizontal',
    ticker: true,
    tickerHover: true,
    speed: 30000, // Slower = more readable
    useCSS: false, // Required for tickerHover to work
    minSlides: 1,
    maxSlides: 3,
    slideWidth: 400,
    slideMargin: 50
  });
});
</script>

<style>
.news-ticker li {
  white-space: nowrap;
  font-size: 16px;
  line-height: 40px;
}
</style>
```

## Summary

bxSlider provides a comprehensive solution for implementing responsive content sliders and carousels in jQuery-based web applications. Common use cases include image galleries with thumbnail navigation, product carousels for e-commerce sites, hero banners with auto-play functionality, testimonial sliders, news tickers, and video presentations. The plugin's extensive configuration options allow developers to customize every aspect of slider behavior, from transition modes and timing to touch interactions and accessibility features.

Integration with existing projects is straightforward: include the jQuery library and bxSlider files, create a container element with child slides, and initialize with `$('.selector').bxSlider()`. The public API methods enable programmatic control for custom navigation, while callback functions provide hooks for analytics tracking, lazy loading, and synchronization with other page elements. For complex implementations, the plugin supports custom pagers, external controls, dynamic slide addition via `reloadSlider()`, and complete teardown with `destroySlider()`. The combination of CSS3 transitions with jQuery animation fallbacks ensures smooth performance across all browsers while maintaining full functionality on touch devices.