Skip to content

API Documentation

Jump to bottom
Michael Weber edited this page May 9, 2019 · 32 revisions

ScrollCarousel is an out-of-the-box accessible & responsive horizontal carousel.

Philosophy

Carousels suck! See: ShouldIUseACarousel.com. Sometimes, though, you've no choice but to implement one. So, Scroll Carousel is an attempt to create a carousel with as much native accessibility as possible by doing much of the job with HTML & CSS. Rather than being a necessity, the Javascript in this plugin adds convenience to the carousel.

How it works

Your HTML should look something like this:

<div class="container">
  <ul class="carousel">
    <li class="item"></li>
    <li class="item"></li>
    <li class="item"></li>
  </ul>
</div>

Carousel Structure

  • The blue outer box is the container element for the carousel and should be the direct and only parent. It exists to restrict the maximum width of the carousel and as a position: relative anchor point for the absolutely positioned buttons that are generated.
  • The inner cyan-colored box is the carousel itself. In your Javascript file, this is the element you will call the scrollCarousel() initialization method on. This element is intended to overflow the container element with overflow-x: scroll. If Javascript is disabled, the horizontal scrollbar isn't removed to allow for easy navigation of the carousel items.
  • Each light pink box is a carousel item. When the carousel is scrolled, the plugin calculates which item is nearest to the alignment point and fires the alignment function (after a set debounce period) to snap the closest child into place within the carousel.

Once you have imported the plugin into your project, just call the initialization method scrollCarousel() on the parent element of the individual items of your carousel. Using the example above:

$('.carousel').scrollCarousel();

Styling

Included in the repository is a minified CSS file with the minimum styles necessary for Scroll Carousel.

As of now you need to manually added the appropriate classes to your HTML elements, but soon it will dynamically add the appropriate classes once it is instantiated on the correct element. I also have plans to allow dynamic class naming of the generated arrows/indicators buttons so you can easily style the buttons to your liking.

API Options

You may pass options via an object in the init method, like, using the example above,

$('.carousel').scrollCarousel({option: 'value'});

or as a data-carousel data attribute on the carousel element.

<div class="carousel" data-carousel="{'option': 'value'}"></div>

snapOffset (WIP)

Type: Number | Default: 0

snapOffset represents a number, in pixels that you would like to adjust the positioning of items by. In this example, a snapOffset of 15 shifts the alignment point 15px to the right. Were it set to -15, it would shift the alignment point 15px to the left.

$('carousel').scrollCarousel({offsetSnap: 15});

ADD IMAGE REPRESENTATION

snapAlignment

Type: String - enums => ['left', 'right', 'center'] | Default: 'left'

snapAlignment's value sets the child items snapping behavior. 'left' snaps children to the left edge of the carousel container, 'right' to the right, and 'center' centers the child element.

ADD IMAGE REPRESENTATION

snapLeeway

Type: Number | Default: 5

When the carousel is scrolled manually, snapLeeway dictates the margin of difference in pixels needed for an alignment to occur. If an element's boundary falls within snapLeeway's value from where it is supposed to align, Scroll Carousel does not attempt to align it further.

preventEdgeSnapping

Type: Boolean | Default: true

preventEdgeSnapping disables snap alignment at the very end or beginning of a carousel. This is useful because at some widths, the first and last items of the carousel become obscured after alignment occurs.

ADD IMAGE REPRESENTATION

buttonType

Type: String - enums => ['arrows', 'indicators'] | Default: 'arrows'

Scroll Carousel generates navigation buttons to assist viewing it's contents. By default, 'arrows' creates 'Prev' and 'Next' buttons that progress or regress through the contents. 'indicators' creates a button for each item of the carousel that represents which item is currently focused and allows you to jump directly to specific items.

ADD EXAMPLE AND IMAGE REPRESENTATION

showIndicatorNumbers

Type: Boolean | Default: false

When using indicator buttons, you may optionally enable the buttons to display which number slide each button represents.

fadeObscured (WIP)

Type: Boolean | Default: false

fadeObscured generates a slightly opaque overlay on top of items that are partially in view but not focused.

fadeOpacity (WIP)

Type: Number - range => [0, 0.1, 0.2... 1] | Default: 0.5

This option allows you to set the opacity of the overlay created by fadeObscured, if you have it enabled.

animationLength

Type: Number - milliseconds | Default: 250

animationLength sets the snap animation timing using milliseconds.

disableAnimation

Type: Boolean | Default: false

If you would like to disable the animation & snap the scroll into position immediately following the debounce period, set this value to true.

debounce

Type: Number - milliseconds | Default: 200

Scroll Carousel's snap alignment is by default debounced to ensure a smooth user experience. The debounce option allows you to adjust how long of a delay you'd like before the debounced alignment function is called.

Clone this wiki locally