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
- Create the HTML structure. Use a
<div>withrole="region"andaria-roledescription="carousel"to wrap the carousel. Inside, place a<ul>withrole="list"that contains each slide as an<li>. Each slide should haverole="group"andaria-roledescription="slide". Add anaria-labelto the carousel container with a descriptive name. - Add the slide content. Inside each
<li>, place an image with a meaningfulalttext. If the slide contains more than just an image (e.g., a caption), wrap it in a<figure>and use<figcaption>for the caption. - 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>withrole="group"andaria-label="Carousel controls". - Set up the CSS. Hide all slides except the first one using
display: noneon.slide:not(.active). Style the active slide withdisplay: block. Add transitions if desired (e.g., fade or slide). Ensure the carousel container has a fixed height oraspect-ratioto prevent layout shift. - Write the JavaScript logic. Select all slides, the previous/next buttons, and the indicators. Define a variable
currentIndexstarting at 0. Create a functionshowSlide(index)that updates theactiveclass on the slides and indicators, and updates thearia-hiddenattribute (true for inactive slides, false for active). Also update thetabindexof the slides—only the active slide should be focusable (tabindex=”0″), others should be tabindex=”-1″. - Wire up the buttons. Add click event listeners to the previous and next buttons. For next, increment
currentIndexand wrap around using modulo; for previous, decrement and wrap. CallshowSlidewith the new index. - Add indicator functionality. For each indicator button, add a click listener that sets
currentIndexto the index of that indicator and callsshowSlide. - Implement keyboard navigation. Add a
keydownlistener 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. - Add ARIA live region. Include a visually hidden
<p>witharia-live="polite"that announces the current slide number and total slides. Update its text inshowSlide(e.g., “Slide 2 of 5”). This helps screen reader users know when the slide changes. - 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
altattributes 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-hiddenunchanged can cause screen readers to read hidden slides. - Ignoring the live region. Without an
aria-liveregion, screen reader users won’t know when the slide changes.
Tips
- Use a
figureelement for slides with captions—this provides a semantic association between the image and its caption. - Add
aria-currentto 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-motionby 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
activeclass 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 thekeydownlistener 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-hiddenis set correctly on slides. - Indicators not updating. Make sure each indicator has a unique
data-indexor similar, and that the click handler uses that index. Also check that you’re toggling theactiveclass 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
- Fix Apps Not Downloading From Play Store
- Secure a Samsung Galaxy After a Zero-Day Disclosure
- What to Check Before Installing Linux Alongside Windows
- Fix OEM Activation Error 0xc004c060 in Windows 10
- Why Does My App Run One Query for the List and One per Item?
- Fix Google Chrome Has Stopped Working