Accessibility

The Accessibility plugin enhances Embla Carousel with ARIA support, helping ensure a more inclusive experience for users relying on assistive technologies.

Example

Installation

Start by installing the npm package and save it to your dependencies:

<script src="https://unpkg.com/embla-carousel-accessibility/embla-carousel-accessibility.umd.js"></script>

npm install embla-carousel-accessibility --save

pnpm add embla-carousel-accessibility

yarn add embla-carousel-accessibility

Options

Below follows an exhaustive list of all Accessibility options and their default values.

active

{ active: false | true }

Setting this to false will not activate or deactivate the plugin. Useful when used together with the breakpoints option to toggle the plugin active/inactive depending on media queries.

breakpoints

{   active: false,  '(min-width: 768px)': { active: true }}

An object with options that will be applied for a given breakpoint by overriding the options at the root level.

rootNode

{ rootNode: null | (emblaRoot) => emblaRoot.parentElement }

The node from which the carousel should look for previous and next buttons, dots, and the live region. This affects setupPrevAndNextButtons, setupDotButtons, and setupLiveRegion methods. By default, the plugin will use the carousel root node as the starting point.

announceChanges

{ announceChanges: false | true }

When set to true, the plugin will announce slide changes to assistive technologies using an ARIA live region. Note that you need to provide a live region element using the setupLiveRegion method for this to work.

carouselAriaLabel

{ carouselAriaLabel: 'Carousel' }

Provides an accessible label for the carousel container, which is read by screen readers to describe the carousel's purpose.

carouselAriaRoleDescription

{ carouselAriaRoleDescription: 'carousel' }

Gives a brief description of the carousel's role, which is read by screen readers to provide additional context about the carousel component.

carouselRole

{ carouselRole: 'region' }

Defines the ARIA role for the carousel container. The default value is region, which indicates that the carousel is a significant section of the page.

previousButtonAriaLabel

{ previousButtonAriaLabel: 'Go to previous Slide' }

Provides an accessible label for the previous button, which is read by screen readers to describe its purpose. For this to apply, you have to register your previous and next buttons using the setupPrevAndNextButtons method.

nextButtonAriaLabel

{ nextButtonAriaLabel: 'Go to next Slide' }

Provides an accessible label for the next button, which is read by screen readers to describe its purpose. For this to apply, you have to register your previous and next buttons using the setupPrevAndNextButtons method.

slideAriaRoleDescription

{ slideAriaRoleDescription: 'slide' }

Gives a brief description of each slide's role, which is read by screen readers to provide additional context about the slide component.

slideRole

{ slideRole: 'group' }

Defines the ARIA role for each slide. The default value is group, which indicates that the slide is a collection of related elements.

slideAriaLabel

{  slideAriaLabel: (    hasAnyGroupedSlides,     firstSlideIndex,     lastSlideIndex,     totalSlides,     selectedSnapIndex,    totalSnaps  ) => `Slide ${firstSlideIndex + 1} of ${totalSlides}`}

A callback function that generates an accessible label for each slide, providing context about its position and group within the carousel. The function receives parameters that help determine the appropriate label based on the slide's index and grouping.

dotButtonAriaLabel

{  dotButtonAriaLabel: (    hasAnyGroupedSlides,     firstSlideIndex,     lastSlideIndex,     totalSlides,     selectedSnapIndex,    totalSnaps  ) => `Go to slide ${firstSlideIndex + 1} of ${totalSlides}`}

Provides an accessible label for each dot button, which is read by screen readers to describe its purpose. The function receives parameters that help determine the appropriate label based on the slide's index and grouping.

liveRegionContent

{  liveRegionContent: (    hasAnyGroupedSlides,     firstSlideIndex,     lastSlideIndex,     totalSlides,     selectedSnapIndex,    totalSnaps  ) => `Showing slide ${firstSlideIndex + 1} of ${totalSlides}`}

Generates the content for the ARIA live region, which is announced to assistive technologies when the slide changes. The function receives parameters that help determine the appropriate content based on the slide's index and grouping.

Methods

Below follows an exhaustive list of all Accessibility methods with their respective parameters and return values.

setupPrevAndNextButtons

emblaApi.plugins().accessibility?.setupPrevAndNextButtons(  document.querySelector('.embla__prev-button') | '.embla__prev-button',  document.querySelector('.embla__next-button') | '.embla__next-button')

Registers the previous and next buttons for the carousel, allowing the Accessibility plugin to add appropriate ARIA attributes and labels to them. Provide an element or a selector string for each button.

setupDotButtons

emblaApi.plugins().accessibility?.setupDotButtons(  document.querySelector('.embla__dots') | '.embla__dots')

Registers the dot buttons wrapper for the carousel, allowing the Accessibility plugin to add appropriate ARIA attributes and labels to each dot button. Provide an element or a selector string for the dots wrapper.

setupLiveRegion

emblaApi.plugins().accessibility?.setupLiveRegion(  document.querySelector('.embla__live-region') | '.embla__live-region')

Registers the live region element for the carousel, allowing the Accessibility plugin to announce slide changes to assistive technologies. Provide an element or a selector string for the live region.

setUpdateLiveRegion

emblaApi.plugins().accessibility?.setUpdateLiveRegion(true | false)

Controls whether the live region should be updated when the slide changes. This can be useful for preventing unnecessary announcements when autoplay or auto scroll is active.

updatePrevAndNextButtons

emblaApi.plugins().accessibility?.updatePrevAndNextButtons()

Programmatically updates the ARIA attributes and labels for the previous and next buttons. By default, this is handled automatically on mount, when the selected snap changes.

updateLiveRegion

emblaApi.plugins().accessibility?.updateLiveRegion()

Programmatically updates the content of the live region. By default, this is handled automatically on mount and when the selected snap changes.

updateSlides

emblaApi.plugins().accessibility?.updateSlides([0, 1, 2])

Programmatically updates the ARIA attributes and labels for all slides. Optionally, you can provide an array of snap indices to update slides that belong to these snaps only. By default, this is handled automatically on mount, when the selected snap changes, on focus in and out.

updateDotButtons

emblaApi.plugins().accessibility?.updateDotButtons([0, 1, 2])

Programmatically updates the ARIA attributes and labels for all dot buttons. Optionally, you can provide an array of snap indices to update dots that belong to these snaps only. By default, this is handled automatically on mount, when the selected snap changes, on focus in and out.