a11y-slider

v0.4.22

Published

2 years ago

Library for accessible sliders

Downloads

5,868

0High
0Medium
0Low

mmahandev

accessible slider carousel javascript typescript library es6 js accessibility a11y

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="//unpkg.com/a11y-slider@latest/dist/a11y-slider.css" />

<!-- End of <body> -->
<script src="//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

Non-modern browsers that doesn't support ScrollToOptions will not have smooth scrolling when switching slides. A polyfill like smoothscroll can be used to fix this.

Todo

Examples
Look into not removing width style from slides
Make autoprefix run automatically
Better resize throttling
Look into enabling useCapture for scroll events to prevent window events