toc

Carousel

A carousel is a scrollable list of visual items that change size as they move through the layout.

Mountains

Coastline

Desert

<md-gb-carousel aria-label="Destinations" style="--item-width: 186px">
  <md-gb-carousel-item label="Mountains">
    <div style="background: var(--md-sys-color-primary-container)"></div>
    <span slot="label">Mountains</span>
  </md-gb-carousel-item>
  <md-gb-carousel-item label="Coastline">
    <div style="background: var(--md-sys-color-secondary-container)"></div>
    <span slot="label">Coastline</span>
  </md-gb-carousel-item>
  <md-gb-carousel-item label="Desert">
    <div style="background: var(--md-sys-color-tertiary-container)"></div>
    <span slot="label">Desert</span>
  </md-gb-carousel-item>
</md-gb-carousel>

Install with shadcn/ui: npx shadcn@latest add https://material-web.dev/3.0/r/md-carousel.json (setup)

Usage guidelines

Link to “Usage guidelines”

Lead with visuals. Items emphasize an image and can carry a brief label that adapts to the item size.
Choose a layout. Use multi-browse for varied sizes, hero to feature an item, uncontained for items that run edge to edge, and full-screen for one item at a time.
Match scrolling to the layout. Snap scrolling suits multi-browse, hero and full-screen. Free scrolling suits uncontained.

This component is new in M3 Expressive.

Anatomy

Link to “Anatomy”

A carousel holds md-gb-carousel-item elements. Each has a visual in its default slot and an optional label.

Lisbon

Kyoto

Oslo

<md-gb-carousel aria-label="Cities" style="--item-width: 186px">
  <md-gb-carousel-item label="Lisbon">
    <div style="background: var(--md-sys-color-primary-container)"></div>
    <span slot="label">Lisbon</span>
  </md-gb-carousel-item>
  <md-gb-carousel-item label="Kyoto">
    <div style="background: var(--md-sys-color-secondary-container)"></div>
    <span slot="label">Kyoto</span>
  </md-gb-carousel-item>
  <md-gb-carousel-item label="Oslo">
    <div style="background: var(--md-sys-color-tertiary-container)"></div>
    <span slot="label">Oslo</span>
  </md-gb-carousel-item>
</md-gb-carousel>

Examples

Link to “Examples”

Hero

Link to “Hero”

Set layout="hero" to feature a large item with small items beside it. Add alignment="center" to center it.

<md-gb-carousel layout="hero" aria-label="Featured trips" style="--item-width: 186px">
  <md-gb-carousel-item label="Mountains">
    <div style="background: var(--md-sys-color-primary-container)"></div>
  </md-gb-carousel-item>
  <md-gb-carousel-item label="Coastline">
    <div style="background: var(--md-sys-color-secondary-container)"></div>
  </md-gb-carousel-item>
  <md-gb-carousel-item label="Desert">
    <div style="background: var(--md-sys-color-tertiary-container)"></div>
  </md-gb-carousel-item>
</md-gb-carousel>

Uncontained

Link to “Uncontained”

Set layout="uncontained" for items of one size that scroll freely. uncontained-multi-aspect allows items with different aspect ratios.

<md-gb-carousel layout="uncontained" aria-label="Albums" style="--item-width: 186px">
  <md-gb-carousel-item label="Morning">
    <div style="background: var(--md-sys-color-primary-container)"></div>
  </md-gb-carousel-item>
  <md-gb-carousel-item label="Noon">
    <div style="background: var(--md-sys-color-secondary-container)"></div>
  </md-gb-carousel-item>
  <md-gb-carousel-item label="Evening">
    <div style="background: var(--md-sys-color-tertiary-container)"></div>
  </md-gb-carousel-item>
  <md-gb-carousel-item label="Night">
    <div style="background: var(--md-sys-color-primary-container)"></div>
  </md-gb-carousel-item>
  <md-gb-carousel-item label="Dawn">
    <div style="background: var(--md-sys-color-secondary-container)"></div>
  </md-gb-carousel-item>
</md-gb-carousel>

Linked items

Link to “Linked items”

Give an item href to make it a link. Without it, the item is a button.

Mountains

Coastline

Desert

<md-gb-carousel aria-label="Destinations" style="--item-width: 186px">
  <md-gb-carousel-item label="Mountains" href="/mountains">
    <div style="background: var(--md-sys-color-primary-container)"></div>
    <span slot="label">Mountains</span>
  </md-gb-carousel-item>
  <md-gb-carousel-item label="Coastline" href="/coastline">
    <div style="background: var(--md-sys-color-secondary-container)"></div>
    <span slot="label">Coastline</span>
  </md-gb-carousel-item>
  <md-gb-carousel-item label="Desert" href="/desert">
    <div style="background: var(--md-sys-color-tertiary-container)"></div>
    <span slot="label">Desert</span>
  </md-gb-carousel-item>
</md-gb-carousel>

Scroll mode and orientation

Link to “Scroll mode and orientation”

Set scroll-mode to snap or free, and orientation to horizontal or vertical. The full-screen layout scrolls vertically by default.

HTML

CSS

<md-gb-carousel layout="full-screen" scroll-mode="snap" aria-label="Stories">
  <md-gb-carousel-item label="Morning">
    <div style="background: var(--md-sys-color-primary-container)"></div>
  </md-gb-carousel-item>
  <md-gb-carousel-item label="Noon">
    <div style="background: var(--md-sys-color-secondary-container)"></div>
  </md-gb-carousel-item>
  <md-gb-carousel-item label="Evening">
    <div style="background: var(--md-sys-color-tertiary-container)"></div>
  </md-gb-carousel-item>
</md-gb-carousel>

md-gb-carousel {
  inline-size: 100%;
  block-size: 280px;
}

Accessibility

Link to “Accessibility”

The carousel is a region with the role description "carousel". Name it with aria-label.
Each item's label is its accessible name, read with its position in the set.
Tab or the arrow keys move between items, and Enter or Space activates the focused one.
Give images a text alternative, or hide decorative ones.

Compatibility

Link to “Compatibility”

Material Design 3Spec checked48% tokens

97 of 299 buildable spec units are tested, 16 are excluded with a written reason and 0 are uncovered (the target is 0). 14 of 29 token declarations match the spec (48%), and 15 have no spec token.

carousel on m3.material.io (opens in a new tab) How compliance is measured

BaselineWidely availableChrome 124Edge 124Firefox 125Safari 17.4

The component’s own CSS and JavaScript rely only on web platform features that are Baseline widely available: it works in Chrome 124, Edge 124, Firefox 125, Safari 17.4 and later.

Newer features it uses where the browser has them (progressive enhancements):

Cursor styles (opens in a new tab) Limited availability degrades safely where it is missing
overscroll-behavior (opens in a new tab) Limited availability degrades safely where it is missing
scrollbar-width (opens in a new tab) Newly available degrades safely where it is missing
user-select (opens in a new tab) Limited availability used inside an @supports guard
CSS.registerProperty() (opens in a new tab) Newly available JavaScript, feature-detected or optional

Browser support Learn more about Baseline (opens in a new tab)

WAI-ARIAaxe and ARIA 1.3 passButtonLink

Roles the component renders: button (opens in a new tab), link (opens in a new tab), list (opens in a new tab), listitem (opens in a new tab), region (opens in a new tab).

Follows the WAI-ARIA Authoring Practices: Button (opens in a new tab), Link (opens in a new tab).

1 rendered state run through axe-core and the WAI-ARIA 1.3 role and attribute rules in a real browser, with no known gaps.

WAI-ARIA 1.3 (opens in a new tab) ARIA Authoring Practices (opens in a new tab) Accessibility

Lighthouse99 · 93 · 100 · 100

Performance
Accessibility
Best practices
SEO

Audits under 90:

Elements with an ARIA `[role]` that require children to contain a specific `[role]` are missing some or all of those required children.
Eliminate render-blocking resources
Minify JavaScript
Reduce unused JavaScript
Enable text compression
Network dependency tree
Render blocking requests

Lighthouse 12.8.2 (desktop, 2026-11-08) on the component alone: its first example on a page of its own, without this site's shell. The modules are the development build (not bundled or minified), so the performance score is indicative.

Open the test page About Lighthouse (opens in a new tab)

API reference

Link to “API reference”

<md-gb-carousel>

Link to “<md-gb-carousel>”

A Material Design carousel.

Properties

Link to “Properties”

Property	Attribute	Type	Default
`alignment` Start or center alignment of the hero layout.	`alignment`	`CarouselAlignment`	`'start'`
`layout` The carousel layout.	`layout`	`CarouselLayout`	`'multi-browse'`
`orientation` The scrolling axis. Defaults to vertical for the full-screen layout and horizontal for the others.	`orientation`	`CarouselOrientation`
`scrollMode` `snap` snaps items into the layout when released; `free` lets them stop anywhere. Defaults to `free` for uncontained layouts and `snap` for the others.	`scroll-mode`	`CarouselScrollMode`

Slots

Link to “Slots”

Slot	Description
default	The `md-gb-carousel-item` elements.

Methods

Link to “Methods”

Method	Description
`next` (behavior?: ScrollBehavior) => void	Scrolls to the next item.
`previous` (behavior?: ScrollBehavior) => void	Scrolls to the previous item.
`relayout` () => void	Recomputes the layout. The carousel does this on resize and when items or properties change; call it after changing `--item-width` or other layout tokens.
`scrollToItem` (index: number, behavior?: ScrollBehavior) => void	Scrolls an item to its snapped position in the layout.

CSS parts

Link to “CSS parts”

Part	Description
`::part(carousel)`	The container.
`::part(scroller)`	The scroll container (`role="list"`).

CSS custom properties

Link to “CSS custom properties”

Property	Description
`--container-color`	Item container color, behind its visual.
`--container-elevation`	Item elevation.
`--container-shape`	Item corner radius.
`--full-screen-item-spacing`	Space between full-screen items.
`--height`	Carousel height (default 221px, Compose samples).
`--item-spacing`	Space between items.
`--item-width`	Preferred large item width (multi-browse, hero) or item width (uncontained). `auto` picks a layout default.
`--label-padding`	Item label padding.
`--label-scrim-color`	Scrim behind item labels.
`--label-text`	Item label typography.
`--label-text-axes`	Item label font variation settings.
`--label-text-color`	Item label color.
`--label-text-tracking`	Item label letter spacing.
`--padding-block`	Top/bottom container padding.
`--padding-inline`	Leading/trailing container padding.
`--small-item-max-width`	Maximum small item width.
`--small-item-min-width`	Minimum small item width.

<md-gb-carousel-item>

Link to “<md-gb-carousel-item>”

A Material Design carousel item.

Properties

Link to “Properties”

Property	Attribute	Type	Default
`disabled` Whether the item is disabled.	`disabled`	`boolean`	`false`
`href` Makes the item a link to this URL.	`href`	`string`	`''`
`label` The accessible name of the item. Defaults to its label text.	`label`	`string`	`''`
`outlined` Whether the item has an outline (`with-outline` tokens).	`outlined`	`boolean`	`false`
`target` The link target, with `href`.	`target`	`string`	`''`

Slots

Link to “Slots”

Slot	Description
default	The item visual, such as an `<img>` or `<video>`. It is sized to cover the item.
`label`	Brief label text shown over the visual.

CSS parts

Link to “CSS parts”

Part	Description
`::part(action)`	The button or link that activates the item.
`::part(content)`	The masked visual and label.
`::part(frame)`	The masked outline, elevation and focus ring.
`::part(item)`	The item root.
`::part(label)`	The label container.

CSS custom properties

Link to “CSS custom properties”

Property	Description
`--carousel-item-fraction`	Read-only: the item's current size between the carousel's smallest (0) and large (1) item sizes.
`--carousel-item-size`	Read-only: the item's current masked size along the scrolling axis.
`--with-outline-outline-color`	Outline color of outlined items.
`--with-outline-outline-width`	Outline width of outlined items.

Carousel

Usage guidelines

Anatomy

Examples

Hero

Uncontained

Linked items

Scroll mode and orientation

Accessibility

Compatibility

API reference

<md-gb-carousel>

Properties

Slots

Methods

CSS parts

CSS custom properties

<md-gb-carousel-item>

Properties

Slots

CSS parts

CSS custom properties

Download & copy

Download

Copy

Customize theme