Skip to content

ppromerojr/embla-carousel

 
 

Repository files navigation


Embla Carousel Logo

Embla Carousel

Extensible low level carousels for the web. Extend it with basic JavaScript and build awesome physics simulated carousels. Dependency free and 100% open source.


 TRY DEMO 


options   ·   api   ·   codesandbox


JavaScript   React


Installation

NPM

npm install embla-carousel

QuickStart

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)

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
Align the slides relative to the carousel viewport.
This option aligns the slides to the start or end edge of the carousel viewport. Slides will be centered if no value is provided. Note that slide alignments will be overrided for slides at the start or end when used together with containScroll , that prevents excessive scrolling at the beginning or end.

Type: string
Allowed values: start center end
Default value: center


Usage

const options = { align: 'start' }
const embla = EmblaCarousel(emblaNode, options)

containerSelector
A query selector for the container that holds the slides.
This option allows for the use of a custom query selector to match the container that holds the slides. If no value is provided Embla will match any immediate html tag. All immediate children of this container will be treated as slides.

Type: string
Allowed values: any
Default value: *


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>

slidesToScroll
Scroll past the given number of slides.
This option groups slides together. Drag interactions, dot navigation, and previous/next buttons are mapped to group slides into the given number. For example, if the option is set to 2, every two slides will be treated as a single slide.

Type: number
Allowed values: any
Default value: 1


Usage

const options = { slidesToScroll: 2 }
const embla = EmblaCarousel(emblaNode, options)
.embla__slide {
  flex: 0 0 50%; /* Show 2 slides in viewport */
}

containScroll
Contain slides to the carousel viewport.
This option clears empty space that causes excessive scrolling at the beginning or the end. Note that this will override the chosen alignment for slides at the beginning or the end if necessary, in order to get rid of the empty space.

Type: boolean
Allowed values: true false
Default value: false


Usage

const options = { containScroll: true }
const embla = EmblaCarousel(emblaNode, options)

draggable
Allow drag interactions to scroll the carousel.
This option enables for scrolling the carousel with mouse and touch interactions. They're are enabled by default. Use this option to turn this feature off if you have good reasons to limit the accessibility of the carousel.

Type: boolean
Allowed values: true false
Default value: true


Usage

const options = { draggable: false }
const embla = EmblaCarousel(emblaNode, options)

dragFree
Enable momentum scrolling for drag interactions.
This option enables momentum scrolling, where the carousel continues to scroll for a while after finishing the scroll gesture by releasing the mouse/touch input. The speed and duration of the continued scrolling is proportional to how vigorous the scroll gesture was.

Type: boolean
Allowed values: true false
Default value: false


Usage

const options = { dragFree: true }
const embla = EmblaCarousel(emblaNode, options)

loop
Enable infinite looping for the carousel.
This option enables infinite looping. Slides need relative positioning in order for this to work. If the carousel only has one slide it will fall back to non looping behaviour. Note that containScroll will be ignored if loop is enabled because the empty space is already filled with looping slides.

Type: boolean
Allowed values: true false
Default value: false


Usage

const options = { loop: true }
const embla = EmblaCarousel(emblaNode, options)
.embla__slide {
  position: relative; /* Needed for loop to work */
}

speed
Set scroll speed triggered by API navigation.
This option enables adjustment of the scroll speed when triggered by any of the API methods 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.

Type: number
Allowed values: any
Default value: 10


Usage

const options = { speed: 15 }
const embla = EmblaCarousel(emblaNode, options)

startIndex
Select index of the initial scroll snap.
This options allows the selection of the initial scroll snap position. First scroll snap index starts at 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.

Type: number
Allowed values: any
Default value: 0


Usage

const options = { startIndex: 3 }
const embla = EmblaCarousel(emblaNode, options)

selectedClass
Choose classname applied to the selected slides.
This options allows for a custom classname that will be applied to the selected slide. In most cases, only one slide will be selected at a time. However, when 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.

Type: string
Allowed values: any
Default value: is-selected


Usage

const options = { selectedClass: 'my-selected-class' }
const embla = EmblaCarousel(emblaNode, options)

draggableClass
Choose classname applied to the draggable container.
This options allows for a custom classname that will be applied to the carousel container if the carousel is 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.

Type: string
Allowed values: any
Default value: is-draggable


Usage

const options = { draggableClass: 'my-draggable-class' }
const embla = EmblaCarousel(emblaNode, options)
.my-draggable-class {
  cursor: grab;
}

draggingClass
Choose classname applied to the container when dragging.
This options allows for a custom classname that will be applied to the carousel container on mousedown or touchstart, if the carousel is 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.

Type: string
Allowed values: any
Default value: is-dragging


Usage

const options = { draggingClass: 'my-dragging-class' }
const embla = EmblaCarousel(emblaNode, options)
.my-dragging-class {
  cursor: grabbing;
}

API

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()}!`)
})
containerNode
Grab the container node that holds the slides.
This API method returns the container node that holds the slides. If a custom selector is used by utilising the containerSelector option this will return the matching element, otherwise it will return the first immediate child of the Embla node passed to EmblaCarousel.

Parameters: none
Return Type: Node.ELEMENT_NODE


Usage

const embla = EmblaCarousel(emblaNode, options)
const emblaContainer = embla.containerNode()

slideNodes
Grab the slide nodes inside the container.
This API method returns an array with the slide nodes inside the carousel container. Use this handy method if you want to manipulate the slide nodes in some way. You can also grab the length of the array to get the slide count.

Parameters: none
Return Type: Node.ELEMENT_NODE[]


Usage

const embla = EmblaCarousel(emblaNode, options)
const emblaSlides = embla.slideNodes()

scrollNext
Scroll to the next snap point if possible.
This API method scrolls to the next snap point if possible. If the 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.

Parameters: none
Return Type: 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>

scrollPrev
Scroll to the previous snap point if possible.
This API method scrolls to the previous snap point if possible. If the 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.

Parameters: none
Return Type: 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>

scrollTo
Scroll to a snap point by its unique index.
This API method scrolls to the snap point that matches the given index. When the loop option is enabled, the carousel will seek the closest way to the target. Useful for creating dot navigation together with the scrollSnapList method.

Parameters: index: number
Return Type: 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>

canScrollPrev
Check the possiblity to scroll to a previous snap point.
This API method returns a boolean that indicates if the carousel can scroll to a previous snap point from its current position. Note that if the loop option is enabled it will always return true. For example, it can be used to disable or enable a scroll to previous button.

Parameters: none
Return Type: 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>

canScrollNext
Check the possiblity to scroll to a next snap point.
This API method returns a boolean that indicates if the carousel can scroll to a next snap point from its current position. Note that if the loop option is enabled it will always return true. For example, it can be used to disable or enable a scroll to next button.

Parameters: none
Return Type: 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>

selectedScrollSnap
Retrieve the index of the selected snap point.
This API method returns the index of the current selected snap point. If the 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.

Parameters: none
Return Type: number


Usage

const embla = EmblaCarousel(emblaNode, options)
const currentSnapIndex = embla.selectedScrollSnap()

previousScrollSnap
Retrieve the index of the previous snap point.
This API method returns the index of the previously selected snap point. If the 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.

Parameters: none
Return Type: number


Usage

const embla = EmblaCarousel(emblaNode, options)
const previousSnapIndex = embla.previousScrollSnap()

scrollSnapList()

Returns an array of all scroll snap points, each containing slide numbers and slide nodes.

Demo - embla.scrollSnapList()
scrollProgress()

Returns how far the carousel has scrolled from 0 at the first slide to 1 at the end.

Demo - embla.scrollProgress()
clickAllowed()

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.

Demo - embla.clickAllowed()
changeOptions(options)

Applies passed options by doing all the necessary calculations and initialising the carousel from scratch.

Demo - embla.changeOptions()
destroy()

Removes all styles applied to DOM nodes and kills all event listeners for this Embla instance.

Demo - embla.destroy()
on(event, callback)

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.
Demo - embla.on()
off(event, callback)

Ends subscription to a custom Embla event by removing the passed callback. This works for all events listed on the on method.

Demo - embla.off()

CodeSandbox

Get started instantly with one of the CodeSandboxes below.

Embla Carousel CodeSandbox   Basic Setup - With Previous, Next & Dot buttons.

Embla Carousel CodeSandbox   Autoplay - Example of how to setup Autoplay.

Browser Support

Embla has been tested in the browsers listed below. Special thanks goes to BrowserStack.

Embla Carousel browser support   IE - 11

Embla Carousel browser support   Edge - Latest 2 versions

Embla Carousel browser support   Chrome - Latest 2 versions

Embla Carousel browser support   Firefox - Latest 2 versions

Embla Carousel browser support   Safari - Latest 2 versions


Contributors

Thank you to all contributors for making Embla Carousel awesome! Contributions are welcome.


Open Source

Copyright © 2019-present, David Cetinkaya.
Embla is MIT licensed 💖

· · ·

Embla Carousel BrowserStack

About

🍀 Extensible low level carousels for the web

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • TypeScript 97.7%
  • JavaScript 2.3%