Quaff

QCarousel

Carousels let users browse items in a scrolling row or full-screen view. Add navigation buttons and labels to guide browsing.

1 of 6
info QCarousel API Source
interface QCarouselProps<T> extends Omit<
  HTMLAttributes<HTMLElement>,
  "children" | "onselect"
>
alignment
?: "start" | "center" = "start"
Alignment of the prominent items. @default start
aspectRatio
?: (item: T, index: number) => number = undefined
Width/height ratio for each uncontained-multi-aspect item, clamped to 9:16–16:9.
controls
?: boolean = true
Shows navigation buttons below the items. Provide showAll or another accessible alternative if hidden. @default true
height
?: string = undefined
CSS height of the items. Full-screen defaults to 100svh; other layouts to 240px.
itemLabel
?: (item: T, index: number) => string = undefined
Accessible item name, followed by its position and total count.
itemWidth
?: number = 360
Preferred maximum large item width in pixels; fixed width for uncontained items. @default 360
items
: readonly T[] = undefined
Items in display order.
labels
?: Partial<QCarouselLabels> = undefined
Translations for control labels, role descriptions, and item positions (zero-based index).
onselect
?: (item: T, index: number) => void = undefined
Makes each item a button. Called on pointer or keyboard activation.
snap
?: boolean = undefined
Snap to items. Defaults to false for uncontained layouts; always true for full-screen.
value
?: number = $bindable(0)
Zero-based prominent item index. Bindable. @default 0
variant
?: CarouselVariant = "multi-browse"
Material 3 layout. @default multi-browse

Usage

Multi-browse
The default layout gives several items room while masking items at the edges. Items grow into view as you scroll. Bind value to the prominent item's zero-based index. Set onselect to make each slide a button; its content must then contain no other interactive elements.
1 of 6

Prominent photo: 1 of 6

Choose a photo to select it.

Uncontained
Items retain their width as they scroll past the container edge. This layout scrolls freely by default; set snap to align items after scrolling.
1 of 6
Uncontained Multi-aspect
Preserve different image proportions with aspectRatio. Ratios are constrained between portrait 9:16 and landscape 16:9; all items share the same height.
1 of 6
Hero
A large leading item highlights one image while a smaller trailing item invites further browsing. Contained layouts snap to an item by default.
1 of 6
Centered Hero
Center the featured item with glimpses of neighboring images on both sides. Use alignment="center" with multi-browse for a centered group instead.
2 of 6
Full-screen
Present one item at a time with vertical scrolling and mandatory snapping. Use this layout for portrait screens; choose another variant for landscape layouts. The default height is 100svh, reduced to 448px in this embedded example.
1 of 6
Accessibility
Give each carousel an aria-label or aria-labelledby, and provide meaningful alternative text for images. Previous and next buttons allow navigation without dragging. When an item is focused, use arrow keys to browse and Home or End to reach the first or last item. Full-screen carousels use Up and Down. Native links and controls inside non-actionable slides retain their keyboard behavior.

There is no automatic rotation. Scrolling respects the reduced-motion preference. Keep the default controls or provide equivalent accessible navigation when setting controls=false. Translate navigation and position announcements through labels.

The optional showAll snippet can link to a separate vertical collection. See the Material 3 carousel specs.

Privacy Policy