Carousel

Material Design 3 carousel for browsing related content with horizontal snapping and optional controls. Not intended for long-form reading sequences that require stable vertical scanning.

Basic Usage

Use the default contained variant for image or content galleries. Snap behavior and controls help users browse related slides predictably.

Slide 1 Slide 2 Slide 3 
<ds-carousel show-navigation show-indicators>
  <img src="slide1.jpg" alt="Slide 1">
  <img src="slide2.jpg" alt="Slide 2">
  <img src="slide3.jpg" alt="Slide 3">
</ds-carousel>

Initial Value

Set an initial configuration with autoplay and custom interval.

Auto slide 1 Auto slide 2 Auto slide 3 
<ds-carousel auto-play auto-play-interval="3000" show-indicators>
  <img src="slide1.jpg" alt="Slide 1">
  <img src="slide2.jpg" alt="Slide 2">
  <img src="slide3.jpg" alt="Slide 3">
</ds-carousel>

Variants/Formats

Choose from contained, uncontained, or hero layout variants.

Contained

Contained 1 Contained 2 Contained 3

Uncontained

Uncontained 1 Uncontained 2 Uncontained 3

Hero

Hero 1

Hero 2

Hero 3

 
<ds-carousel variant="contained">...</ds-carousel>
<ds-carousel variant="uncontained">...</ds-carousel>
<ds-carousel variant="hero">...</ds-carousel>

States

Combine features for navigation, indicators, autoplay, and looping states.

Navigation Only

Nav 1 Nav 2 Nav 3

Indicators Only

Ind 1 Ind 2 Ind 3

Loop Enabled

Loop 1 Loop 2 Loop 3

Interactive Example

Track carousel events from control buttons, indicators, or scrolling.

Interactive 1 Interactive 2 Interactive 3
Waiting for carousel events... 
const carousel = document.querySelector('#interactive-carousel');
carousel.addEventListener('ds-carousel:change', (event) => {
  console.log(event.detail.index, event.detail.total);
});

API Reference

Attributes

Attribute Type Default Description
variant string contained contained, uncontained, or hero
show-navigation boolean false Shows previous and next buttons
show-indicators boolean false Shows indicator controls
auto-play boolean false Auto-advances slides
auto-play-interval number 5000 Auto-play delay in milliseconds
loop boolean false Enables looped navigation

Properties

Property Type Description
variant string Gets/sets variant
showNavigation boolean Gets/sets navigation visibility
showIndicators boolean Gets/sets indicators visibility
autoPlay boolean Gets/sets autoplay state
autoPlayInterval number Gets/sets autoplay interval
loop boolean Gets/sets looping state
currentIndex number Current slide index (read only)

Events

Event Detail Description
ds-carousel:change { index, total } Fired when active slide changes
ds-carousel:scroll { index, total } Fired while scrolling updates active slide

CSS Parts

Part Description
container Main container
viewport Scrollable viewport
navigation Navigation controls container
nav-button Navigation buttons
indicators Indicator list
indicator Single indicator

CSS Custom Properties

Property Description
--ds-carousel-height Carousel viewport height
--ds-carousel-gap Override slide gap
--ds-carousel-nav-button-size Navigation button size (defaults to --ds-size-control-lg)
--ds-carousel-nav-icon-size Navigation icon size (defaults to --ds-size-icon-lg)

Accessibility

  • ArrowLeft and ArrowRight provide keyboard navigation between slides.
  • Navigation buttons include descriptive aria-label attributes.
  • Indicators use tablist and tab semantics with selected state.
  • Focus-visible styles are applied to host, controls, and indicators.

Usage Guidelines

  • Use contained variant for product or content cards in standard layouts.
  • Use hero variant for prominent landing sections with immersive visuals.
  • Enable autoplay only when slides are informational and not task-critical.
  • Keep slide content concise to support quick scanning and accessibility.