Skip to content

README.md

Latest commit

 

History

History
139 lines (113 loc) · 4.73 KB

README.md

File metadata and controls

139 lines (113 loc) · 4.73 KB
Raw

Carousel

Material Design 3 Carousel component.

Carousels show a scrollable collection of items with dynamic sizing, snapping, navigation buttons, and pagination indicators.

Usage

import 'material/carousel/carousel.js'
import 'material/carousel/carousel-item.js'

Basic Multi-Browse Carousel (Default)

<md-carousel>
  <md-carousel-item headline="Image 1" subhead="Subtitle description">
    <img src="photo1.jpg" alt="Photo 1" />
  </md-carousel-item>
  <md-carousel-item headline="Image 2" subhead="Subtitle description">
    <img src="photo2.jpg" alt="Photo 2" />
  </md-carousel-item>
  <md-carousel-item headline="Image 3" subhead="Subtitle description">
    <img src="photo3.jpg" alt="Photo 3" />
  </md-carousel-item>
</md-carousel>

Uncontained Layout

<md-carousel layout="uncontained" item-width="320px">
  <md-carousel-item>
    <md-card type="outlined" class="p16">
      <h3>Card 1</h3>
      <p>Card content</p>
    </md-card>
  </md-carousel-item>
  <md-carousel-item>
    <md-card type="outlined" class="p16">
      <h3>Card 2</h3>
      <p>Card content</p>
    </md-card>
  </md-carousel-item>
</md-carousel>

Hero Layout (Start-aligned)

<md-carousel layout="hero" indicators>
  <md-carousel-item headline="Featured Product" subhead="New Release">
    <img src="hero1.jpg" alt="Hero 1" />
  </md-carousel-item>
  <md-carousel-item headline="Special Offer" subhead="Limited time">
    <img src="hero2.jpg" alt="Hero 2" />
  </md-carousel-item>
</md-carousel>

Centered-Hero Layout

<md-carousel layout="centered-hero" indicators loop>
  <md-carousel-item headline="Movie 1">
    <img src="poster1.jpg" alt="Poster 1" />
  </md-carousel-item>
  <md-carousel-item headline="Movie 2">
    <img src="poster2.jpg" alt="Poster 2" />
  </md-carousel-item>
  <md-carousel-item headline="Movie 3">
    <img src="poster3.jpg" alt="Poster 3" />
  </md-carousel-item>
</md-carousel>

Full-Screen Layout

<md-carousel layout="full-screen" indicators autoplay="5000" loop style="height: 400px;">
  <md-carousel-item headline="Slide 1">
    <img src="slide1.jpg" alt="Slide 1" />
  </md-carousel-item>
  <md-carousel-item headline="Slide 2">
    <img src="slide2.jpg" alt="Slide 2" />
  </md-carousel-item>
</md-carousel>

<md-carousel> Properties & Attributes

Property / Attribute Type Default Description
layout 'multi-browse' | 'uncontained' | 'hero' | 'centered-hero' | 'full-screen' 'multi-browse' Carousel layout strategy.
item-width / itemWidth string '' Custom item width (e.g. '300px').
item-spacing / itemSpacing number 8 Spacing between items in px.
navigation 'auto' | 'always' | 'none' 'auto' Controls visibility of previous/next navigation buttons.
indicators boolean false When true, shows pagination indicator dots.
autoplay number 0 Delay in milliseconds for automatic sliding (0 = disabled).
loop boolean false When true, wraps navigation around when reaching edges.
active-index / activeIndex number 0 0-based index of the currently active slide.
scroll-snap / scrollSnap boolean true Enables/disables CSS scroll-snapping.
hide-scrollbar / hideScrollbar boolean true Hides the horizontal scrollbar.

Methods

  • next(): Scrolls to the next slide.
  • previous(): Scrolls to the previous slide.
  • scrollToIndex(index, behavior = 'smooth'): Scrolls to a specific slide index.

Events

  • change: Dispatched when the active item changes. event.detail contains { index, item }.
  • scroll: Dispatched when the carousel is scrolled.

<md-carousel-item> Properties & Attributes

Property / Attribute Type Default Description
shape string 'var(--md-sys-shape-corner-extra-large, 28px)' Corner radius or shape ('small', 'medium', 'large', 'extra-large', 'full').
type 'filled' | 'elevated' | 'outlined' | '' '' Container card style variant.
interactive boolean false Enables ripple, focus-ring, and hover elevation effects.
href string '' Link URL when clicking the carousel item.
target string '' Target window for link ('_blank', etc.).
headline string '' Headline text overlay.
subhead string '' Subhead text overlay.

Slots

  • (default): Media or card content (images, custom elements).
  • headline: Custom headline content.
  • subhead: Custom subhead content.
  • scrim: Custom scrim overlay.
  • action: Action buttons or icons in the item overlay.