sodcalculator

10 Tech How-To

Build an Accessible JavaScript Image Carousel

Guide 10-57664 · Updated · Step by step

This guide walks you through building an image carousel that is keyboard-navigable, screen-reader friendly, and works with assistive technologies. You’ll create a simple, robust carousel from scratch using semantic HTML, ARIA attributes, and vanilla JavaScript. No frameworks or libraries are needed—just a basic understanding of HTML, CSS, and JavaScript.

What You’ll Need

  • A text editor (VS Code, Sublime, etc.)
  • A web browser (Chrome, Firefox, Safari, Edge)
  • Basic knowledge of HTML, CSS, and JavaScript
  • Images to display (you can use placeholder images)

Step-by-Step

  1. Create the HTML structure. Use a <div> with role="region" and aria-roledescription="carousel" to wrap the carousel. Inside, place a <ul> with role="list" that contains each slide as an <li>. Each slide should have role="group" and aria-roledescription="slide". Add an aria-label to the carousel container with a descriptive name.
  2. Add the slide content. Inside each <li>, place an image with a meaningful alt text. If the slide contains more than just an image (e.g., a caption), wrap it in a <figure> and use <figcaption> for the caption.
  3. Create the controls. Add two buttons for previous and next navigation, and a set of slide indicator buttons (one per slide). Give each button a clear aria-label (e.g., “Previous slide”, “Next slide”, “Go to slide 2”). Place them in a <div> with role="group" and aria-label="Carousel controls".
  4. Set up the CSS. Hide all slides except the first one using display: none on .slide:not(.active). Style the active slide with display: block. Add transitions if desired (e.g., fade or slide). Ensure the carousel container has a fixed height or aspect-ratio to prevent layout shift.
  5. Write the JavaScript logic. Select all slides, the previous/next buttons, and the indicators. Define a variable currentIndex starting at 0. Create a function showSlide(index) that updates the active class on the slides and indicators, and updates the aria-hidden attribute (true for inactive slides, false for active). Also update the tabindex of the slides—only the active slide should be focusable (tabindex=”0″), others should be tabindex=”-1″.
  6. Wire up the buttons. Add click event listeners to the previous and next buttons. For next, increment currentIndex and wrap around using modulo; for previous, decrement and wrap. Call showSlide with the new index.
  7. Add indicator functionality. For each indicator button, add a click listener that sets currentIndex to the index of that indicator and calls showSlide.
  8. Implement keyboard navigation. Add a keydown listener on the carousel container. When the focus is inside the carousel, handle ArrowLeft and ArrowRight to move to previous/next slides. Also handle Home and End to jump to the first and last slides. Prevent default behavior to avoid page scrolling.
  9. Add ARIA live region. Include a visually hidden <p> with aria-live="polite" that announces the current slide number and total slides. Update its text in showSlide (e.g., “Slide 2 of 5”). This helps screen reader users know when the slide changes.
  10. Test with a screen reader. Use a screen reader (NVDA, VoiceOver) to verify that the carousel is announced correctly, that buttons have proper labels, and that slide changes are announced. Also test keyboard-only navigation to ensure focus moves correctly.

Common Mistakes

  • Not using semantic HTML. Using <div> for everything without roles makes it hard for screen readers to interpret.
  • Missing alt text. Images without alt attributes are announced as “image” or ignored, making the content inaccessible.
  • Forgetting to manage focus. If inactive slides remain focusable, keyboard users will tab through hidden content. Always set tabindex="-1" on hidden slides.
  • Not updating ARIA attributes. Leaving aria-hidden unchanged can cause screen readers to read hidden slides.
  • Ignoring the live region. Without an aria-live region, screen reader users won’t know when the slide changes.

Tips

  • Use a figure element for slides with captions—this provides a semantic association between the image and its caption.
  • Add aria-current to the active indicator to help screen reader users know which slide is active.
  • Consider adding a pause/play button for auto-rotating carousels, and ensure it respects prefers-reduced-motion by disabling auto-rotate when the user prefers reduced motion.
  • Keep the carousel simple. Avoid complex animations that may cause vestibular issues. If you use transitions, make them short and subtle.
  • Test with real users. If possible, have people with disabilities test your carousel to uncover issues you might miss.

Troubleshooting

  • Carousel not showing any slides. Check that your CSS correctly hides non-active slides. Ensure the active class is applied to the first slide initially.
  • Keyboard navigation not working. Verify that the carousel container has tabindex="0" to make it focusable. Also check that the keydown listener is attached to the container and that you’re not accidentally preventing default on other keys.
  • Screen reader not announcing slide changes. Ensure the live region is present and its text is updated. Also check that aria-hidden is set correctly on slides.
  • Indicators not updating. Make sure each indicator has a unique data-index or similar, and that the click handler uses that index. Also check that you’re toggling the active class on the correct elements.
  • Images not loading. Verify the image paths are correct. Use relative paths or absolute URLs. If using placeholders, ensure the service is accessible.
  • Focus gets trapped. If you have a modal-like carousel, ensure you’re not trapping focus unintentionally. For a simple carousel, allow focus to move naturally.

Frequently Asked Questions

Why do I need ARIA roles if I’m using HTML5?

ARIA roles help screen readers understand the structure and behavior of custom widgets like carousels. HTML5 alone doesn’t provide enough semantics for a carousel.

Should I use a <button> or a <div> for carousel controls?

Always use <button> for interactive controls—they are keyboard accessible and have built-in click handling. A <div> would require extra code to make it accessible.

How do I make the carousel work on touch devices?

You can add touch event listeners (touchstart, touchmove, touchend) to detect swipes. However, ensure that keyboard and screen reader support remain intact. Swipe gestures are an enhancement, not a replacement.

Can I use CSS-only carousels?

CSS-only carousels (using radio buttons and :checked) are possible, but they often lack full keyboard support and screen reader semantics. JavaScript gives you more control over accessibility.

How do I handle a carousel with dynamic content (e.g., from an API)?

After loading new slides, you need to re-initialize the carousel: update the slide list, indicators, and reset the current index. Also update the live region to reflect the new total.

Is it okay to auto-play the carousel?

Auto-play can be distracting and problematic for users with cognitive disabilities. If you use it, provide a pause button and respect prefers-reduced-motion by disabling auto-play when the user prefers reduced motion.

Related

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →