Extensible low level carousels for the web. Extend it with basic JavaScript and build awesome physics simulated carousels. Dependency free and 100% open source.
options · api · codesandbox
NPM
npm install embla-carousel
HTML
<div class="embla">
<div class="embla__container">
<div class="embla__slide">
Slide 1
</div>
<div class="embla__slide">
Slide 2
</div>
<div class="embla__slide">
Slide 3
</div>
<div class="embla__slide">
Slide 4
</div>
</div>
</div>
CSS
.embla {
overflow: hidden;
}
.embla__container {
display: flex;
}
.embla__slide {
position: relative; /* Needed if loop: true */
flex: 0 0 100%; /* Choose any slide width */
}
JavaScript
import EmblaCarousel from 'embla-carousel'
const emblaNode = document.querySelector('.embla')
const options = { loop: true }
const embla = EmblaCarousel(emblaNode, options)
Configure Embla by passing an options object as the second argument. Default values are:
const embla = EmblaCarousel(emblaNode, {
align: 'center',
containerSelector: '*',
slidesToScroll: 1,
containScroll: false,
draggable: true,
dragFree: false,
loop: false,
speed: 10,
startIndex: 0,
selectedClass: 'is-selected',
draggableClass: 'is-draggable',
draggingClass: 'is-dragging',
})
Align the slides relative to the carousel viewport.
containScroll
,
that prevents excessive scrolling at the beginning or end.
string
start
center
end
center
Usage
const options = { align: 'start' }
const embla = EmblaCarousel(emblaNode, options)
A query selector for the container that holds the slides.
string
any
*
Usage
const emblaNode = document.querySelector('.embla')
const options = { containerSelector: '.my-container-selector' }
const embla = EmblaCarousel(emblaNode, options)
<div class="embla">
<div class="my-container-selector">
...slides
</div>
</div>
Scroll past the given number of slides.
2
, every two slides will be treated as a single slide.
number
any
1
Usage
const options = { slidesToScroll: 2 }
const embla = EmblaCarousel(emblaNode, options)
.embla__slide {
flex: 0 0 50%; /* Show 2 slides in viewport */
}
Contain slides to the carousel viewport.
boolean
true
false
false
Usage
const options = { containScroll: true }
const embla = EmblaCarousel(emblaNode, options)
Allow drag interactions to scroll the carousel.
boolean
true
false
true
Usage
const options = { draggable: false }
const embla = EmblaCarousel(emblaNode, options)
Enable momentum scrolling for drag interactions.
boolean
true
false
false
Usage
const options = { dragFree: true }
const embla = EmblaCarousel(emblaNode, options)
Enable infinite looping for the carousel.
containScroll
will be ignored if loop is enabled because the empty space is already filled with looping slides.
boolean
true
false
false
Usage
const options = { loop: true }
const embla = EmblaCarousel(emblaNode, options)
.embla__slide {
position: relative; /* Needed for loop to work */
}
Set scroll speed triggered by API navigation.
scrollNext
,
scrollPrev
and
scrollTo
. Use a higher number for faster scrolling. Drag interactions are not affected by this because the speed in these cases is determined by how vigorous the drag gesture was.
number
any
10
Usage
const options = { speed: 15 }
const embla = EmblaCarousel(emblaNode, options)
Select index of the initial scroll snap.
0
. If slides are mapped to groups with the
slidesToScroll
option, some slides share the same scroll snap index. For example, if it's set to 2
slide one and two will be at index 0, while slide three and four will be at index 1 and so on.
number
any
0
Usage
const options = { startIndex: 3 }
const embla = EmblaCarousel(emblaNode, options)
Choose classname applied to the selected slides.
slidesToScroll
is more than 1
and/or
containScroll
is active, slides are mapped to groups. This means that the selected class will be added to multiple slides at a time.
string
any
is-selected
Usage
const options = { selectedClass: 'my-selected-class' }
const embla = EmblaCarousel(emblaNode, options)
Choose classname applied to the draggable container.
draggable
. Use it to style the carousel accordingly. For example, you can show a grab cursor when a draggable carousel is hovered. If no value is provided it will fall back to is-draggable
.
string
any
is-draggable
Usage
const options = { draggableClass: 'my-draggable-class' }
const embla = EmblaCarousel(emblaNode, options)
.my-draggable-class {
cursor: grab;
}
Choose classname applied to the container when dragging.
draggable
. Use it to style the carousel accordingly. For example, you can show a grabbing cursor when a pointer is down. If no value is provided it will fall back to is-dragging
.
string
any
is-dragging
Usage
const options = { draggingClass: 'my-dragging-class' }
const embla = EmblaCarousel(emblaNode, options)
.my-dragging-class {
cursor: grabbing;
}
Embla exposes API methods that can be used to control the carousel externally. Example usage:
embla.scrollNext()
embla.scrollTo(2)
embla.changeOptions({ loop: true })
embla.on('select', () => {
console.log(`Selected snap index is ${embla.selectedScrollSnap()}!`)
})
Grab the container node that holds the slides.
containerSelector
option this will return the matching element, otherwise it will return the first immediate child of the Embla node passed to EmblaCarousel.
none
Node.ELEMENT_NODE
Usage
const embla = EmblaCarousel(emblaNode, options)
const emblaContainer = embla.containerNode()
Grab the slide nodes inside the container.
none
Node.ELEMENT_NODE[]
Usage
const embla = EmblaCarousel(emblaNode, options)
const emblaSlides = embla.slideNodes()
Scroll to the next snap point if possible.
loop
option is disabled and the carousel is on the last snap point, this method will do nothing. When loop is enabled, it will always be able to scroll to the next snap point. Useful for creating a scroll next button for example.
none
undefined
Usage
const embla = EmblaCarousel(emblaNode, options)
const nextButton = emblaNode.querySelector('.embla__next')
nextButton.addEventListener('click', embla.scrollNext, false)
<button class="embla__next" type="button">
Scroll Next
</button>
Scroll to the previous snap point if possible.
loop
option is disabled and the carousel is on the first snap point, this method will do nothing. When loop is enabled, it will always be able to scroll to the previous snap point. Useful for creating a scroll previous button for example.
none
undefined
Usage
const embla = EmblaCarousel(emblaNode, options)
const prevButton = emblaNode.querySelector('.embla__prev')
prevButton.addEventListener('click', embla.scrollPrev, false)
<button class="embla__prev" type="button">
Scroll Previous
</button>
Scroll to a snap point by its unique index.
loop
option is enabled, the carousel will seek the closest way to the target. Useful for creating dot navigation together with the
scrollSnapList
method.
index: number
undefined
Usage
const embla = EmblaCarousel(emblaNode, options)
const rewindButton = emblaNode.querySelector('.embla__rewind')
rewindButton.addEventListener('click', () => embla.scrollTo(0), false)
<button class="embla__rewind" type="button">
Rewind
</button>
Check the possiblity to scroll to a previous snap point.
loop
option is enabled it will always return true. For example, it can be used to disable or enable a scroll to previous button.
none
boolean
Usage
const embla = EmblaCarousel(emblaNode, options)
const prevButton = emblaNode.querySelector('.embla__prev')
const togglePrevButtonEnabled = () => {
if (embla.canScrollPrev()) {
prevButton.removeAttribute('disabled')
} else {
prevButton.setAttribute('disabled', 'disabled')
}
}
embla.on('select', togglePrevButtonEnabled);
<button class="embla__prev" type="button">
Scroll Previous
</button>
Check the possiblity to scroll to a next snap point.
loop
option is enabled it will always return true. For example, it can be used to disable or enable a scroll to next button.
none
boolean
Usage
const embla = EmblaCarousel(emblaNode, options)
const nextButton = emblaNode.querySelector('.embla__next')
const toggleNextButtonEnabled = () => {
if (embla.canScrollNext()) {
nextButton.removeAttribute('disabled')
} else {
nextButton.setAttribute('disabled', 'disabled')
}
}
embla.on('select', toggleNextButtonEnabled);
<button class="embla__next" type="button">
Scroll Next
</button>
Retrieve the index of the selected snap point.
slidesToScroll
option is more than 1
some slides will be grouped together and share the same index. For example, when it's set to 2
, every two slides will share the same index. In this case, slide 1
and 2
will share index 0
and slide 3
and 4
will share index 1
and so on.
none
number
Usage
const embla = EmblaCarousel(emblaNode, options)
const currentSnapIndex = embla.selectedScrollSnap()
Retrieve the index of the previous snap point.
slidesToScroll
option is more than 1
some slides will be grouped together and share the same index. For example, when it's set to 2
, every two slides will share the same index. In this case, slide 1
and 2
will share index 0
and slide 3
and 4
will share index 1
and so on.
none
number
Usage
const embla = EmblaCarousel(emblaNode, options)
const previousSnapIndex = embla.previousScrollSnap()
Returns an array of all scroll snap points, each containing slide numbers and slide nodes.
✨ Demo -embla.scrollSnapList()
Returns how far the carousel has scrolled from 0
at the first slide to 1
at the end.
embla.scrollProgress()
Returns if a click should be accepted. It returns false
if the carousel is dragged. On touch devices it also returns false
when the carousel is scrolling.
embla.clickAllowed()
Applies passed options by doing all the necessary calculations and initialising the carousel from scratch.
✨ Demo -embla.changeOptions()
Removes all styles applied to DOM nodes and kills all event listeners for this Embla instance.
✨ Demo -embla.destroy()
Subscribes to a custom Embla event by firing the passed callback. Below is a list of events you can subscribe to:
init
- When the carousel has been initialised for the first time.destroy
- When the carousel has been destroyed.select
- When a new target slide has been selected.scroll
- When carousel is scrolled.resize
- When window size changes.dragStart
- When carousel dragging begins.dragEnd
- When carousel dragging ends.
embla.on()
Ends subscription to a custom Embla event by removing the passed callback. This works for all events listed on the on
method.
embla.off()
Get started instantly with one of the CodeSandboxes below.
Basic Setup
- With Previous, Next & Dot buttons.
Autoplay
- Example of how to setup Autoplay.
Embla has been tested in the browsers listed below. Special thanks goes to BrowserStack.
Thank you to all contributors for making Embla Carousel awesome! Contributions are welcome.
Copyright © 2019-present, David Cetinkaya.
Embla is MIT licensed 💖
· · ·