Skip to content
An infinite carousel Web Component built with modern CSS and just a little Javascript
HTML TypeScript CSS JavaScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci
.vscode
example
lib
.gitignore
LICENSE
README.md
demo.gif
package-lock.json
package.json
rollup.config.js
tsconfig.json

README.md

Published on webcomponents.org npm

CircleCI

infinite-carousel-wc

An infinite carousel Web Component built with modern CSS and just a little Javascript. Supports both horizontal and vertical scrolling.

infinite-carousel-wc demo

Demo

Installation

You can integrate infinite-carousel-wc via <script> tag or via NPM.

Via <script> tag

In the <head> of your index.html put a script tag like this:

<script
  type="module"
  src="https://unpkg.com/infinite-carousel-wc/dist/esm/infinite-carousel-wc.min.js"
></script>
<script
  nomodule
  src="https://unpkg.com/infinite-carousel-wc/dist/iife/infinite-carousel-wc.min.js"
></script>

Now you can use the infinite-carousel-wc element anywhere in your html, JSX, template, etc.

Via NPM

npm install infinite-carousel-wc --save

And then you need to import the module before you can use it in your html/jsx/template:

import "infinite-carousel-wc";

Web Component Browser Support

This web component uses HTML templates, the shadow DOM, and custom elements. If you need to polyfill for any of these standards then take a look at the web components polyfill.

Polyfills

This custom element uses CSS Scroll Snap, IntersectionObserver and Smooth Scrolling. Browser support for Scroll Snap is pretty good (this custom element supports both v0 and v1 of the spec). There is a polyfill for IntersectionObserver and Smooth Scrolling.

A note about IntersectionObserver polyfill on iOS 12.1 and below: you might need to configure the polyfill to use polling for the carousel to work properly.

API and Customization

Slots

The infinite carousel works by laying out 3 slots, with slot names of 1, 2, and 3. The slots will be re-ordered in a circular manner as the user swipes/scrolls.

When inifinite-scroller-wc first renders it will show slot 1 as visible (called the "current" position). Slot 2 will be to the right (in the "next" position), and slot 3 will be to the left (in the "previous" position), like this:

"previous" "current" "next"
3 1 2

Remember that "current" is the only slot visible to the user at rest. When the user peaks left or right they will then see the "previous" or "next" slot contents respectively.

When the user swipes/scrolls forward then some CSS will get added to the slots to re-order them (technically the CSS is added to the slot's parents which are encapsulated in the shadow DOM). After 1 swipe/scroll it will look like this:

"previous" "current" "next"
1 2 3

Another swipe forward/next would produce:

"previous" "current" "next"
2 3 1

Swiping/scrolling backward would do the reverse, as you'd expect.

The circular re-ordering allows the user to swipe/scroll "infinitely" in either direction. It is up to the consuming code to listen for the next or previous events. For an example of listening to the event and updating the slot contents take a look at index.html.

Methods

  • goNext()
    • Scrolls to the next slot.
    • Example: document.getElementById("carousel").goNext()
  • goPrevious()
    • Scrolls to the previous slot.
    • Example: document.getElementById("carousel").goPrevious()
  • reset()
    • Resets the slot order to the initial order. Slot 1 will be in the "current" position, slot 2 will be in the "next" position, and slot 3 will be in the "previous" position.
    • Example: document.getElementById("carousel").reset()

Attributes/Properties

  • vertical
    • Add this attribute to make your carousel scroll vertically instead of horizontally.
      • Example: <infinite-carousel-wc vertical></infinite-carousel-wc>
    • Set the property in Javascript to imperatively set vertical scrolling
      • Example: carousel.vertical = true
    • NOTE: Dynamically changing this attribute/property will cause a reset of the slot order (it calls the reset() method).
  • lock
    • Add this attribute to prevent scrolling.
      • Example: <infinite-carousel-wc lock></infinite-carousel-wc>
    • Set the property in Javascript to imperatively disable scrolling
      • Example: carousel.lock = true

Events

  • next
    • Raised after the user has scrolled to the next slot
    • Raised about 200ms before the user is allowed to scroll again
    • event.detail contains an ChangeEventDetail object of the following shape:
      export interface ChangeEventDetail {
        newCurrent: 1 | 2 | 3;
      }
    • ChangeEventDetail is an exported type that you can consume if you are writing your code in Typescript.
    • Example: carousel.addEventListener("next", handleCarouselNext())
  • previous
    • Raised after the user has scrolled to the previous slot
    • Raised about 200ms before the user is allowed to scroll again
    • event.detail contains an ChangeEventDetail object of the following shape:
      export interface ChangeEventDetail {
        newCurrent: 1 | 2 | 3;
      }
    • ChangeEventDetail is an exported type that you can consume if you are writing your code in Typescript.
    • Example: carousel.addEventListener("previous", handleCarouselPrevious())

Styling

You can style the infinite-carousel-wc element as you would any regular element, in CSS. You can see an example in example.css.

Contribute

This project is built with standard HTML/CSS/TS, no frameworks or special web-component compilers here (for maximum simplicity and minimum size). If you want to learn more about writing custom elements see MDN or this web fundamentals page.

npm install
npm start

This will start a live-server on port localhost:8080. Any changes you make to files in lib/ or any changes to example/index.html should get live reloaded.

You can’t perform that action at this time.