search

mmdevcodes / a11y-slider

Library for simple and accessible sliders
https://a11yslider.js.org/
MIT License
53 stars 7 forks source link

readme

A11Y Slider

Library for simple and accessible sliders. Demo and examples

Install

Using npm:

npm install a11y-slider

Using browser:

<!-- In the <head> -->
<link rel="stylesheet" href="https://github.com/mmdevcodes/a11y-slider/blob/master//unpkg.com/a11y-slider@latest/dist/a11y-slider.css" />

<!-- End of <body> -->
<script src="https://github.com/mmdevcodes/a11y-slider/raw/master//unpkg.com/a11y-slider@latest/dist/a11y-slider.js"></script>

Usage

A11YSlider works by using CSS scroll snapping. You can generate a slider by creating an overflowed container and then setting widths all via CSS. Media queries in your CSS will also update the slider.

<style>
  .slider {
    display: flex;
  }

  .slider > * {
    width: 100%;
    flex: 0 0 auto;
  }
</style>

<ul class="slider">
  <li>1</li>
  <li>2</li>
  <li>3</li>
  <li>4</li>
</ul>

<script>
  const slider = new A11YSlider(document.querySelector('.slider'), {
    adaptiveHeight: true,
    dots: false
  });
</script>

A11YSlider(element, options)

The element is the targeted slider element. The options is an optional parameter. See options for more info.

Note: A11YSlider only runs if needed! If A11YSlider detects that all slides are already visible in the container then it will not run.

Options

Option Type Description
container Boolean Default: true
Adds a container element around the slider
arrows Boolean Default: true
Enables prev/next button
prevArrow Node | NodeList Default: <button>
Button to trigger previous slide. A11YSlider will generate one by default. Can be one or multiple HTML elements.
nextArrow Node | NodeList Default: <button>
Button to trigger next slide. A11YSlider will generate one by default. Can be one or multiple HTML elements.
dots Boolean Default: true
Generate navigation dots
adaptiveHeight Boolean Default: false
Height of slider container changes according to each slide's height
skipBtn Boolean Default: true
Adds a skip button before the slider for a11y devices (Can be seen by tabbing)
slidesToShow Number | Null Default: null
The total number of items to be shown. By default A11YSlider will work by default based off your CSS styling. This option hardcodes the width into the HTML for you.
autoplay Boolean Default: false
Enables the automatic change of slides
autoplaySpeed Number Default: 4000
Time between slide changes when autoplay is enabled (milliseconds)
autoplayHoverPause Boolean Default: true
If autoplay is enabled then pause when the slider is hovered
centerMode Boolean Default: false
(EXPERIMENTAL) Makes the center slide active
infinite Boolean Default: true
Makes the slider infinitely loop
disable Boolean Default: false
Disables the slider
responsive Object | Null Default: null
Define options for different viewport widths. See responsive example
customPaging Function | Null Default: null
Define your own custom dots template
swipe Boolean Default: true
Enable swiping

Responsive Option Example

You can have different options per specified viewport width. This behaves like CSS min-width media queries. Your initial options outside of the responsive object will work from your lowest specified viewport and down.

const slider = new A11YSlider(document.querySelector('.slider'), {
  slidesToShow: 1,
  arrows: true, // arrows enabled 767px and down
  dots: false,
  responsive: {
    768: {
      slidesToShow: 2,
      arrows: false
    },
    960: {
      disable: true // slider disabled 960px to 1279px
    },
    1280: {
      disable: false,
      slidesToShow: 4,
      dots: true // dots enabled 1280px and up
    }
  }
});

Custom Paging Example

If you would like your own custom HTML for each dot you can pass in your own function. It must return a string and then this function will be called to create HTML for each individual dot. Note that dots will still be wrapped in a <ul>.

const slider = new A11YSlider(document.querySelector('.slider'), {
  dots: true,
  customPaging: function(index, a11ySlider) {
      return '<button class="mycustombtn">' + index + '</button>';
  }
});

Will output to:

<ul class="a11y-slider-dots">
  <li><button class="mycustombtn">0</button></li>
  <li><button class="mycustombtn">1</button></li>
  <li><button class="mycustombtn">2</button></li>
  <li><button class="mycustombtn">3</button></li>
</ul>

Methods

// Example use of the 'scrollToSlide' method.
// Scrolls to the 3rd slide (0-based index)
slider.scrollToSlide(2);
Method Arguments Description
scrollToSlide Number | Element Scrolls slider to specified slide index (0-based) or slide element
updateOptions Object Enter new set of options (reloads slider)
refreshHeight Sets height of slider to height of the current active slide
destroy Removes everything that the A11YSlider created in the DOM

Events

// Example use of the 'afterChange' event
const sliderEl = document.querySelector('.slider');

sliderEl.addEventListener('afterChange', function(e) {
  console.log(e.detail.currentSlide);
});

const slider = new A11YSlider(sliderEl, {
    infinite: true
});
Event Detail Description
init a11yslider Fires after slider initialization
beforeChange currentSlide, nextSlide, a11yslider Fires before slide change
afterChange currentSlide, a11yslider Fires after slide change
autoplayStart currentSlide, a11yslider Fires when autoplay starts
autoplayStop currentSlide, a11yslider Fires when autoplay stops
destroy a11yslider Fires after the slider is destroyed

Events listeners should be added before initializing the slider if possible. For example init will require it.

Browser support

A11YSlider works on all modern browsers including IE11. See notes for some caveats.

Notes

Todo