Styles and States

The mode — Peek, Paged, Shelf — is the style axis; it sets the item width, the snapping and the indicator (see Overview and Layout). CarouselContainer paints nothing of its own except the page indicator: the colour of every item comes from its content. The states differ by mode, so each mode lists its own below; the rest state is Standard in every mode.

Styles · Page indicator below

Styles · Page indicator over the row

Peek · Standard

Courier in an hour

We pick up at the door and deliver across the city

Intercity, cheaper than a bus

Barranquilla — Cartagena from COP 60 000

Freight from 2 hours

Moving house and furniture delivery

Parcels by scooter

Up to 20 kg, the same day

Taxi at a fixed price

The fare does not change on the way

• Peek Behaviour Snaps to the item's start at the edge inset, one item per swipe.The neighbour peeking in by var(--sp-s28) is the indicator — no dots, no autoplay.
• Standard The first item at var(--sp-s20) from the start edge; the next item peeks in at the end edge. At rest on a snap point.

Peek · Scrolling

Courier in an hour

We pick up at the door and deliver across the city

Intercity, cheaper than a bus

Barranquilla — Cartagena from COP 60 000

Freight from 2 hours

Moving house and furniture delivery

Parcels by scooter

Up to 20 kg, the same day

Taxi at a fixed price

The fare does not change on the way

• Scrolling The row between snap points while the user drags — both neighbours partly visible. On release it settles on the nearest item's start, one item per swipe.

Peek · Item focused

Courier in an hour

We pick up at the door and deliver across the city

Intercity, cheaper than a bus

Barranquilla — Cartagena from COP 60 000

Freight from 2 hours

Moving house and furniture delivery

Parcels by scooter

Up to 20 kg, the same day

Taxi at a fixed price

The fare does not change on the way

• Item Focused Keyboard or screen-reader focus on item 3 scrolls it to its snap point: the next item peeks in by 28 at the end edge, and the previous one shows 12 at the start edge (edge inset − gap). The focus ring is the content's own — shown here with the DS ring.

Peek · End of row

Courier in an hour

We pick up at the door and deliver across the city

Intercity, cheaper than a bus

Barranquilla — Cartagena from COP 60 000

Freight from 2 hours

Moving house and furniture delivery

Parcels by scooter

Up to 20 kg, the same day

Taxi at a fixed price

The fare does not change on the way

• End Of Row The last item aligns to the end edge at var(--sp-s20); the previous item peeks in from the start side by var(--sp-s28). The row cannot scroll further, and there is no peek at the end edge.

Peek · Single item

Courier in an hour

We pick up at the door and deliver across the city

• Single Item One item at the container width minus two var(--sp-s20) edge insets — no scrolling, no snapping, no peek.

Paged · Standard

Courier in an hour

We pick up at the door and deliver across the city

Intercity, cheaper than a bus

Barranquilla — Cartagena from COP 60 000

Freight from 2 hours

Moving house and furniture delivery

Parcels by scooter

Up to 20 kg, the same day

• Paged Behaviour One item per page, W − 2 · edge inset wide; pages are spaced by var(--sp-s8), as in the Figma component.The dots are the indicator. Autoplay is available in this mode only.
• Standard Page 1 at var(--sp-s20) from the start edge; the next page shows 12 at the end edge (edge inset − gap); the first dot elongated in --text-and-icon-primary.

Paged · Scrolling

Courier in an hour

We pick up at the door and deliver across the city

Intercity, cheaper than a bus

Barranquilla — Cartagena from COP 60 000

Freight from 2 hours

Moving house and furniture delivery

Parcels by scooter

Up to 20 kg, the same day

• Scrolling Two pages partly visible while the user drags. A fling stops on the next page and never skips one; the dot changes when the row settles.

Paged · Middle page

Courier in an hour

We pick up at the door and deliver across the city

Intercity, cheaper than a bus

Barranquilla — Cartagena from COP 60 000

Freight from 2 hours

Moving house and furniture delivery

Parcels by scooter

Up to 20 kg, the same day

• Middle Page Page 2 of 4: the second dot elongated in --text-and-icon-primary, the others --surface-contrast-overlay.

Paged · Last page

Courier in an hour

We pick up at the door and deliver across the city

Intercity, cheaper than a bus

Barranquilla — Cartagena from COP 60 000

Freight from 2 hours

Moving house and furniture delivery

Parcels by scooter

Up to 20 kg, the same day

• Last Page The last page with the last dot elongated. With loop off the row stops here, and autoplay ends on it.

Paged · Autoplay running

Courier in an hour

We pick up at the door and deliver across the city

Intercity, cheaper than a bus

Barranquilla — Cartagena from COP 60 000

Freight from 2 hours

Moving house and furniture delivery

Parcels by scooter

Up to 20 kg, the same day

Autoplay running — touch, scroll or focus the row to stop it

• Autoplay Running The pages advance on their own every interval — 7 s by default, 3 s in this live demo — on moveM. Autoplay pauses while the pointer hovers the row (web).

Paged · Autoplay stopped

Courier in an hour

We pick up at the door and deliver across the city

Intercity, cheaper than a bus

Barranquilla — Cartagena from COP 60 000

Freight from 2 hours

Moving house and furniture delivery

Parcels by scooter

Up to 20 kg, the same day

• Autoplay Stopped The row stays on the page the user stopped on. The first interaction — a touch, a swipe, a wheel scroll, keyboard or screen-reader focus — stops autoplay, and it does not resume on its own; there is no pause control. An assistive technology or Reduce Motion holds it off from the start.

Paged · Indicator over the row

Courier in an hour

We pick up at the door and deliver across the city

Intercity, cheaper than a bus

Barranquilla — Cartagena from COP 60 000

Freight from 2 hours

Moving house and furniture delivery

Parcels by scooter

Up to 20 kg, the same day

• Indicator Over the Row pageIndicator: overlay puts the dots over the page's bottom edge, on a --surface-white-overlay pill; the row is as tall as its items.For dark or photo banners where the height counts — the pill reads on them; on a light banner the white 16% all but disappears. Not for pages with text or a button at the bottom centre.

Paged · Indicator alignment

Courier in an hour

We pick up at the door and deliver across the city

Intercity, cheaper than a bus

Barranquilla — Cartagena from COP 60 000

Freight from 2 hours

Moving house and furniture delivery

Parcels by scooter

Up to 20 kg, the same day

Courier in an hour

We pick up at the door and deliver across the city

Intercity, cheaper than a bus

Barranquilla — Cartagena from COP 60 000

Freight from 2 hours

Moving house and furniture delivery

Parcels by scooter

Up to 20 kg, the same day

• Center, Start, End pageIndicatorAlign — center by default, start or end; in both placements. Above: Below at the start, Overlay at the end.At the start or end the indicator sits var(--sp-s12) in from the edge inset. Start is the left edge in LTR and the right in RTL.

Paged · Without page indicator

Courier in an hour

We pick up at the door and deliver across the city

Intercity, cheaper than a bus

Barranquilla — Cartagena from COP 60 000

Freight from 2 hours

Moving house and furniture delivery

Parcels by scooter

Up to 20 kg, the same day

• Without Page Indicator pageIndicator: none turns the page indicator off — the dots and the slot they sit in under the row are gone.The page still snaps and each item still announces its position, but nothing on screen shows that the row scrolls.

Paged · Single item

Courier in an hour

We pick up at the door and deliver across the city

• Single Item One page and no dots — no scrolling, no autoplay.

Shelf · Standard

Intercity

Econom

Freight

Moto

Delivery

Taxi

• Shelf Behaviour Fixed-width items, free scroll with no snapping.The item cut by the edge is the indicator — no dots, no autoplay.
• Standard The first item at var(--sp-s20) from the start edge; the last visible item cut by the end edge.

Shelf · Scrolled

Intercity

Econom

Freight

Moto

Delivery

Taxi

• Scrolled Free scroll — the row rests wherever the momentum ends, with items cut on both edges.

Shelf · Item focused

Intercity

Econom

Freight

Moto

Delivery

Taxi

• Item Focused Keyboard or screen-reader focus scrolls the item fully into view. The focus ring is the content's own — shown here with the DS ring.

Shelf · End of row

Intercity

Econom

Freight

Moto

Delivery

Taxi

• End Of Row The last item aligns to the end edge at var(--sp-s20); the row cannot scroll further.

Shelf · Few items

Intercity

Econom

Freight

• Few Items Items that fit in the row keep their width (var(--sp-100-s96) by default), starting at var(--sp-s20); the rest of the row stays empty. No scrolling. This is the default — Shelf does not stretch its items.

Shelf · Few items, stretched

Intercity

Econom

Freight

• Few Items, Stretched stretchItems: true — the items share the container width minus two var(--sp-s20) edge insets equally: (360 − 40 − 2 · 8) / 3 ≈ 101.Applies only while the items fit; once they overflow, the item width applies and the row scrolls.

Shelf · Single item

Intercity

• Single Item One item at its own width, at var(--sp-s20) from the start edge — no scrolling. With stretchItems it takes the whole row.

Anatomy

A container with a scrolling track of CarouselItems, each with one content slot, and — in Paged — a decorative page indicator. The section title above the row is a separate component.

Courier in an hour

We pick up at the door and deliver across the city

Intercity, cheaper than a bus

Barranquilla — Cartagena from COP 60 000

Freight from 2 hours

Moving house and furniture delivery

Parcels by scooter

Up to 20 kg, the same day

1

2

3

4

• 1
  Track --cc-edge — the edge inset on both ends, also the snap point.The scrolling row; the container clips it at its edges. No fill, border or radius of its own.Required.
• 2
  CarouselItem Width per mode, computed from the container width; height follows the content, and every item stretches to the tallest.Required, 1…N.
• 3
  Content Slot Any DS component. The item has no fill or radius of its own; the content brings its shape.Required.
• 4
  Page Indicator One dot per item, the current one elongated. Decorative — not tappable, hidden from the screen reader.Paged only — below the row by default, over it on a pill, or off.

Layout

Every offset is an SP token, and the item width is computed from the container width W — the redlines are drawn at W 360. The item is shown as its empty content slot.

Peek

Paged

Paged · Page indicator

Paged · Page indicator scaling

Shelf

RTL

Animation

Courier in an hour

We pick up at the door and deliver across the city

Intercity, cheaper than a bus

Barranquilla — Cartagena from COP 60 000

Freight from 2 hours

Moving house and furniture delivery

Parcels by scooter

Up to 20 kg, the same day

Live — autoplay advances on moveM every 3 s; touch or scroll the row to stop it

• Programmatic Scroll var(--component-move-m-appear) — moveM, 400 ms on the standard curve.An autoplay advance, or focus moved to an off-screen item.
• Dot Change var(--transforming-state-default) — the dot's colour (candidate).The current dot elongates to var(--sp-s16); the width is not animated.
• Swipe, Fling, Snap The platform's native scroll physics — not tokenised.
• Reduced Motion The motion tokens are zeroed at the token, so a programmatic scroll becomes a jump with no override of its own. Autoplay does not start under Reduce Motion.

Accessibility

The container is a named row; each item is one stop that says where it is in the row. Moving focus scrolls the row — a screen-reader user never has to swipe the row itself to reach an item.

Promotions

Courier in an hour

We pick up at the door and deliver across the city

Intercity, cheaper than a bus

Barranquilla — Cartagena from COP 60 000

Freight from 2 hours

Moving house and furniture delivery

Parcels by scooter

Up to 20 kg, the same day

1

2

3

• 1
  Named By Its Section The row is named by its section title, never "Carousel". TalkBack: the SectionHeader heading carries the name, then the row is a list — CollectionInfo, "in list, 5 items". VoiceOver: the heading, then accessibilityContainerType = .list — "list start". Web: <section aria-roledescription="carousel" aria-label="Promotions">, with "carousel" localised.
• 2
  One Stop Per Item, With Its Position TalkBack: one merged node, "20% off your first ride, Learn more, button, item 2 of 5" — CollectionItemInfo gives the position. VoiceOver: one element whose label ends in a localised "2 of 5"; .button set explicitly — combining does not add it. Web: role="group" aria-roledescription="slide" aria-label="2 of 5", the content follows. An item with several controls is not a stop of its own: the controls are focused one by one and the first carries the position.
• 3
  Decorative Dots Hidden and not tappable — TalkBack clearAndSetSemantics {}, VoiceOver accessibilityHidden(true), web aria-hidden="true" on spans, never buttons inside a hidden container. The item announces the position.
• Paging VoiceOver: a three-finger swipe pages the row (accessibilityScroll) and the app posts a localised "Page 2 of 5" — app-supplied, not produced by the platform. TalkBack: ACTION_SCROLL_FORWARD / BACKWARD page the row and TalkBack speaks its own "showing items 2 to 3 of 5". In RTL forward moves toward the visual left.
• Keyboard And Switch Access Tab reaches each item that holds a control, and focusing it scrolls it to its snap point. Items with nothing focusable make the track itself the stop — tabindex="0", named after the row, with a focus ring; Left / Right move it item by item (mirrored in RTL), Home / End to the ends. No Previous / Next buttons (owner, 2026-11-12): Paged has no single-pointer alternative to the swipe — the WCAG 2.5.1 gap is accepted.
• Autoplay iOS / Android: does not run while TalkBack, VoiceOver, Switch Access / Control or Voice Access / Control is on. Every platform: not under Reduce Motion; stops at the first interaction, one during an advance included.Web: a browser cannot detect a screen reader, and in NVDA / JAWS browse mode the virtual cursor fires no stop event, so the row keeps advancing under a reading user. No live region — the row only scrolls.Known gap: there is no pause control (owner, 2026-11-01), and WCAG 2.2.2 asks for one a reading user can find.
• Edge States Zero items: the row goes with its SectionHeader, no empty list. Single item: no list, no "1 of 1", no slide role. Loading: the skeleton is one "Loading" node; the list is announced once the items arrive, without moving focus. Items changing under focus keep it on the same item.
• Contrast --text-and-icon-primary on --background-primary — the current dot, ≈ 17.8:1 Day / ≈ 17.0:1 Night.--surface-contrast-overlay — the other dots, ≈ 1.6:1 Day / ≈ 2.2:1 Night; decorative, so no contrast floor applies.The current dot also differs in shape — colour is not the only signal.