infinite-carousel-wc
An infinite carousel Web Component built with modern CSS and just a little Javascript. Supports both horizontal and vertical scrolling.
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:
<!-- Or use the minified version -->Now you can use the infinite-carousel-wc element anywhere in your html, JSX, template, etc.
Via NPM
npm install infinite-carousel-wc --saveAnd then you need to import the module before you can use it in your html/jsx/template:
;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>
- Example:
- Set the property in Javascript to imperatively set vertical scrolling
- Example:
carousel.vertical = true
- Example:
- NOTE: Dynamically changing this attribute/property will cause a reset of the slot order (it calls the
reset()method).
- Add this attribute to make your carousel scroll vertically instead of horizontally.
lock- Add this attribute to prevent scrolling.
- Example:
<infinite-carousel-wc lock></infinite-carousel-wc>
- Example:
- Set the property in Javascript to imperatively disable scrolling
- Example:
carousel.lock = true
- Example:
- Add this attribute to prevent scrolling.
currentSlot- This property will return the current slot being shown.
- You cannot set this property programmatically nor can you set it as an attribute.
Events
next- Raised after the user has scrolled to the next slot
- Raised about 200ms before the user is allowed to scroll again
event.detailcontains anChangeEventDetailobject of the following shape:ChangeEventDetailis 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.detailcontains anChangeEventDetailobject of the following shape:ChangeEventDetailis 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 index.html.
Contribute
This project is built with standard HTML/CSS/JS, 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.
The source for this web component is contained in infinite-carousel-wc.js and example usage is in index.html. To debug/run the example you can just open index.html in a browser. For a hot-reload developer experience try using live server in vscode.
You will need the dev dependencies of this project installed to run the post-commit hooks.
npm install