https://github.com/vanillawc/wc-carousel-lite
A web component that wraps HTML elements and forms a horizontal carousel slider out of them.
https://github.com/vanillawc/wc-carousel-lite
carousel carousel-slider custom-elements html javascript vanilla-web-component web-components
Last synced: about 1 year ago
JSON representation
A web component that wraps HTML elements and forms a horizontal carousel slider out of them.
- Host: GitHub
- URL: https://github.com/vanillawc/wc-carousel-lite
- Owner: vanillawc
- License: mit
- Created: 2020-07-26T17:05:17.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2021-05-16T17:34:49.000Z (about 5 years ago)
- Last Synced: 2024-04-26T19:20:16.853Z (about 2 years ago)
- Topics: carousel, carousel-slider, custom-elements, html, javascript, vanilla-web-component, web-components
- Homepage: http://135.181.40.67/wc-carousel-lite/
- Size: 49.8 KB
- Stars: 6
- Watchers: 4
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# wc-carousel-lite
A web component that wraps HTML elements and forms a horizontal carousel slider out of them.
Live demo available [here.](http://135.181.40.67/wc-carousel-lite/)
## Features
Wc-carousel-lite is a standalone vanilla JS web component that does not use shadow DOM.
Component features include:
- content agnostic: carousel items should be able to contain any HTML
- responsive: adapts to different screen widths automatically
- infinite looping of items
- support for swipe gestures (mouse & touch)
- keyboard control (left/right arrow)
- autoplay
## Usage
- create item containers by assigning item class to them
- add content inside the containers
- wrap the item containers inside a carousel component
- set necessary carousel style (width, height)
**HTML example:**
```html
```
**Styling the carousel:**
```css
wc-carousel-lite {
height: 200px;
width: 500px;
margin: auto;
display: flex;
}
```
**Setting width of the space between items:**
```css
.item {
margin-left: 20px;
margin-right: 20px;
}
```
**Another HTML example, using images directly as items:**
```html
```
**Note! Carousel item widths should always be set explicitly.**
## Including the component to an HTML file
1. Import polyfill, this is not needed for modern browsers:
```html
```
2. Import custom element:
```html
```
3. Start using it!
```html
```
## Including the component from NPM
1. Install and import polyfill, this is not needed for modern browsers:
See https://www.npmjs.com/package/@webcomponents/custom-elements
2. Install wc-menu-wrapper NPM package:
```console
npm i @vanillawc/wc-carousel-lite
```
3. Import custom element:
```javascript
import '@vanillawc/wc-carousel-lite'
```
4. Start using it:
```javascript
let carousel = document.createElement("wc-carousel-lite");
carousel.transitionDuration = 1000;
carousel.infinite = true;
carousel.autoplay = true;
carousel.centerBetween = true;
let img = document.createElement("img");
img.setAttribute("src", "./myimage_1.png");
img.setAttribute("width", 300);
img.classList.add("item");
carousel.appendChild(img);
let img_2 = document.createElement("img");
img_2.setAttribute("src", "./myimage_2.png");
img_2.setAttribute("width", 300);
img_2.classList.add("item");
carousel.appendChild(img_2);
document.body.appendChild(carousel);
```
## Attributes
### infinite
If defined, the carousel will be in infinite looping mode.
By default, the carousel will not be in infinite looping mode.
This attribute is a boolean attribute, also known as a valueless attribute.
HTML example:
```html
```
### init-item
Defines which item will be initially shown at the carousel midpoint.
Item numbering begins from zero.
Default value is 0.
HTML example:
```html
```
### autoplay
If defined, the carousel will automatically shift items.
By default, the the carousel will not shift items automatically.
This attribute is a boolean attribute, also known as a valueless attribute.
HTML example:
```html
```
### interval
Defines autoplay shift interval in milliseconds.
Default value is 1000.
This value must be equal or bigger than transition duration.
HTML example:
```html
```
### transition-duration
Defines item shift duration in milliseconds.
Default value is 0, meaning that that the shift takes place instantly.
This value must be equal or smaller than interval.
HTML example:
```html
```
### transition-type
Defines the speed curve of the item shift transition effect.
For possible attribute values, see https://www.w3schools.com/cssref/css3_pr_transition-timing-function.asp
Default value is 'ease'.
HTML example:
```html
```
### center-between
If defined, the items are centered so that the carousel midpoint is between the items.
By default, the items are centered so that the carousel midpoint is in the middle of item.
This attribute is a boolean attribute, also known as a valueless attribute.
HTML example:
```html
```
### direction
Defines autoplay shift direction.
Attribute value must be either 'right' or 'left'
Default value is left (items will shift to left).
HTML example:
```html
```
### no-touch
If defined, touch swiping is disabled.
By default, touch swiping is enabled.
This attribute is a boolean attribute, also known as a valueless attribute.
HTML example:
```html
```
### item
Defines new item class name, if the default class name 'item' can not be used.
HTML example:
```html
```
### touchVelocityLimit
Defines the swipe velocity limit for item shift boosting.
When touch swipe velocity is bigger than the limit, items are shifted with an additional shift.
Default value is 1.5 (pixels per millisecond).
This attribute can't be assigned as an HTML attribute.
### mouseVelocityLimit
Defines the swipe velocity limit for item shift boosting.
When mouse swipe velocity is bigger than the limit, items are shifted with an additional shift.
Default value is 3.0 (pixels per millisecond).
This attribute can't be assigned as an HTML attribute.
### minShiftRequired
Minimum horizontal swipe movement required to shift an item.
Default value is 30 (pixels).
This attribute can't be assigned as an HTML attribute.
## Setting attributes dynamically
*initItem* and *infinite* attributes should be set only when the carousel is not appended to DOM.
*noTouch* value can't be changed once the carousel is appended to DOM.
Example:
```javascript
let carousel = document.createElement("wc-carousel-lite");
carousel.initItem = 2;
carousel.transitionType = 'linear';
carousel.transitionDuration = 1000;
carousel.interval = 2000;
carousel.infinite = true;
carousel.autoplay = true;
carousel.centerBetween = true;
carousel.direction = right;
carousel.touchVelocityLimit = 1;
carousel.mouseVelocityLimit = 2;
carousel.minShiftRequired = 20;
carousel.noTouch = true;
// Add items:
let img = document.createElement("img");
img.setAttribute("src", "./myimage_1.png");
img.setAttribute("width", 300);
img.classList.add("item");
carousel.appendChild(img);
let img_2 = document.createElement("img");
img_2.setAttribute("src", "./myimage_2.png");
img_2.setAttribute("width", 300);
img_2.classList.add("item");
carousel.appendChild(img_2);
// Finally append to DOM:
document.body.appendChild(carousel);
```
## Methods
Methods should not be used unless the carousel is appended to DOM.
### next( shift )
Shifts items to left.
Parameter shift is a number indicating the number of items to be shifted.
Parameter default value is 1.
### prev( shift )
Shifts items to right.
Parameter shift is a number indicating the number of items to be shifted.
Parameter default value is 1.
### goto( index )
Centers item according to index.
Parameter index is a number indicating the item ordinal number beginning from zero.
### play
Starts autoplay.
### stop
Stops autoplay.
## Adding and removing items dynamically
Carousel does not have specific methods to add / remove items dynamically.
When carousel is appended to DOM, items can not be added or removed.
To add / remove items dynamically, do the following:
1. Remove carousel from DOM
2. Add / remove items from the carousel by using appendChild / remove
3. Append carousel back to DOM
## Default attribute values
Default values are defined and modifiable in the custom element constructor.
See file *wc-carousel-lite.js* in *dist* folder.
```javascript
this.item = "item";
this.initItem = 0;
this.transitionDuration = 0;
this.transitionType = "ease";
this.interval = 1000;
this.direction = "left";
this.touchVelocityLimit = 1.5; // pixels per millisecond
this.mouseVelocityLimit = 3.0; // pixels per millisecond
this.minShiftRequired = 30; // minimum x shift required to shift the item (pixels)
```
Infinite, no-touch, center-between and autoplay are all disabled by default and not initialized in constructor at all.
To enable them by default, add following lines to constructor:
```javascript
this.infinite = true;
this.noTouch = true;
this.centerBetween = true;
this.autoplay = true;
```
## Building
Unminified scripts in the dist folder can be used and modified as such, there are no build scripts available for them.
Building is done by executing the minifier script minify.cmd, which is a Linux bash shell script.
Minify.cmd can be found from dist folder.
Building (minifying) requires [terser](https://github.com/terser/terser) command line tool to be installed. It can be installed with following command:
```console
npm install terser -g
```
## Contributing
Questions, suggestions and bug reports are welcome. Safari testing would be nice.
## To do
- dots
- add / remove item methods
## License
Copyright (c) 2020 Jussi Utunen
Licensed under the MIT License