carosans
v3.0.0-alpha
Published
Carosans
Downloads
20
Readme
Carosans
A minimalistic vanilla JS/CSS carousel.
It is currently in alpha, all feedback is welcome!
How to include it into your project
Install
npm i carosans
Import CSS
import 'carosans/src/css/carousel.css'
Import JS
import Carousel from 'carosans'
Alternatively, without import
<!DOCTYPE html>
<head>
<link rel="stylesheet" href="carousel.min.css">
...
</head>
<body>
...
<script src="carousel.min.js"></script>
<script>
Carousel()
</script>
</body>
</html>
How to use
Create a single carousel
Carousel()
The HTML requires the following absolutely minimum structure:
<div class="carousel-outer">
<ul class="carousel-inner">
<li class="carousel-item">
1
</li>
<li class="carousel-item">
2...
</li>
</ul>
</div>
Notes:
- The class names (
carousel-outer
,carousel-inner
,carousel-item
) are required. - It doesn't have to be a list with list items, you can use div's or other elements.
Create multiple carousels
Carousel({
selector: '.my-custom-selector-1',
})
Carousel({
selector: '.my-custom-selector-2',
})
The corresponding HTML:
<!--Carousel 1-->
<div class="carousel-outer my-custom-selector-1">
<div class="carousel-inner">
<div class="carousel-item">
1
</div>
<div class="carousel-item">
2...
</div>
</div>
</div>
<!--Carousel 2-->
<div class="carousel-outer my-custom-selector-2">
<div class="carousel-inner">
<div class="carousel-item">
1
</div>
<div class="carousel-item">
2...
</div>
</div>
</div>
Customizing the carousel
Options object
The Carousel
function accepts an options object
.
Here is an example whith all the available options:
Carousel({
selector: '.my-custom-selector-1', // default: '.carousel-outer'
minMoveToChangePosition: 50, // default: 100
cursor: 'grab', // default: 'auto'
freeMode: true, // default: false
})
API guide:
const carousel = Carousel({
selector: '.my-custom-selector-1',
})
/**
* Get last position.
*/
carousel.pos()
/**
* Check if it is the ending position.
*/
carousel.isEnd()
/**
* Check if it is the starting position.
*/
carousel.isStart()
/**
* Go to next position.
*/
carousel.next(nthNext = 1, rewind = true, isTransitionOn = true)
/**
* Go to previous position.
*/
carousel.prev(nthPrev = 1, rewind = true, isTransitionOn = true)
/**
* Go to nth position.
*/
carousel.to(nth = 0, isTransitionOn = true)
/**
* Get the number of slides in the list.
*/
carousel.length()
/**
* Get the number of slides in view.
*/
carousel.countInView()
/**
* Show how many steps till you reach the end, if you go one step at a time.
* Useful for pagination.
*/
carousel.countSteps()
/**
* Get carousel elements
*/
carousel.getOuter()
carousel.getInner()
carousel.getFirst()
carousel.getNth(nth = 1)
carousel.getLast()
CSS
Carosans has a minimum layer of CSS, to make the carousel work, therefore you have to include carousel.css
into your project.
This basic CSS layer defines some custom properties
that you can use.
Here is an example of using these predefined CSS properties:
/* Carousel one */
.my-custom-selector-1 {
--numOfItemsInView: 1;
--portionVisibleOfExtraItem: .3;
--gapSize: 1rem;
--transitionDuration: .35s;
--transitionTiming: ease;
}
@media (min-width: 50rem) {
.my-custom-selector-1 {
--numOfItemsInView: 3;
--gapSize: 1.5rem;
}
}
@media (min-width: 75rem) {
.my-custom-selector-1 {
--numOfItemsInView: 4;
}
}
/* Carousel two */
.my-custom-selector-2 {
--numOfItemsInView: 1;
--transitionDuration: .35s;
--transitionTiming: ease;
}
@media (min-width: 50rem) {
.my-custom-selector-2 {
--numOfItemsInView: 2;
}
}
@media (min-width: 75rem) {
.my-custom-selector-2 {
--numOfItemsInView: 3;
}
}
Check out the examples
folder, to see how things fit together.
You can find an example on codepen:
https://codepen.io/andrasnagy/full/oNLYgZr
Contribution
A few notes for now:
Useful commands:
npm test
npm run build
npm run lint
Test cases can be found in the examples
folder.
Let me know, if you have any questions or suggestions by opening a new issue.