# Carousel
A carousel is a scrollable list of visual items that change size as they move through the layout.
**Example: A multi-browse carousel of three destinations**
```html
Mountains
Coastline
Desert
```
## 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](https://m3.material.io/blog/building-with-m3-expressive).
## Anatomy
A carousel holds `md-gb-carousel-item` elements. Each has a visual in its default slot and an optional label.
**Example: A carousel of three items, each with a visual and a label**
```html
Lisbon
Kyoto
Oslo
```
## Examples
### Hero
Set `layout="hero"` to feature a large item with small items beside it. Add `alignment="center"` to center it.
**Example: A hero carousel**
```html
```
### Uncontained
Set `layout="uncontained"` for items of one size that scroll freely. `uncontained-multi-aspect` allows items with different aspect ratios.
**Example: An uncontained carousel**
```html
```
### Linked items
Give an item `href` to make it a link. Without it, the item is a button.
**Example: Carousel items that link to pages**
```html
Mountains
Coastline
Desert
```
### 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.
**Example: A full-screen carousel that snaps to one story at a time**
*HTML*
```html
```
*CSS*
```css
md-gb-carousel {
inline-size: 100%;
block-size: 280px;
}
```
## 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.
## API reference
### <md-gb-carousel>
A Material Design carousel.
#### 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
| Slot | Description |
| --- | --- |
| default | The md-gb-carousel-item elements. |
#### 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
| Part | Description |
| --- | --- |
| ::part(carousel) | The container. |
| ::part(scroller) | The scroll container (role="list"). |
#### 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>
A Material Design carousel item.
#### 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
| 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
| 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
| 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. |