Usage

Carousel scrolls a row of items sideways. The root is a region with aria-roledescription="carousel". Each direct child is one slide, named Slide N of M.

gap is a spacing step (0, 0.5, 1, 1.5, 2, 3, or 4). padding uses the same scale and also sets scroll-padding, so a snap point lines up with the content edge. hasSnap snaps each child to the start edge. hasEdgeFade masks the edge that still has overflow.

hasButtons shows previous and next controls when there is something to scroll. A button that cannot move is hidden and disabled. If that button had focus, focus moves to the other one. hasLoop wraps from the last item to the first, and the buttons stay available at both ends while the row overflows. Shift plus the wheel scrolls sideways.

The component exposes scrollNext, scrollPrev, scrollTo, canScrollNext, and canScrollPrev on the template ref.

<script setup lang="ts">
import { Card } from '@astryx-vue/core/Card'
import { Carousel } from '@astryx-vue/core/Carousel'
</script>

<template>
  <Carousel :gap="2" has-snap label="Feature cards" style="max-width: 520px">
    <Card :width="200" :min-height="100">
      Design System
    </Card>
    <Card :width="200" :min-height="100">
      Documentation
    </Card>
  </Carousel>
</template>

Anatomy

Element	Description
Scroll container	The horizontal overflow area that holds all items.
Items	The default slot, rendered in a row inside the scroll container. With hasSnap, each item snaps to the start edge.
Fade edges	Gradient fades on the left and right edges that indicate more content is available. Enabled by default. Set hasEdgeFade to false to turn it off.
Navigation buttons	Prev/next buttons that appear when the content can scroll in that direction. Enabled by default. Set hasButtons to false to turn it off.

Best practices

Guidance	Practices
Do	Give the region a label that names the set, such as “Feature cards”.
Do	Give each card a stable width so one scroll step shows a predictable amount.
Do	Turn on hasSnap when a reader should land on an item, not between two items.
Don't	Put a single short item in a carousel. If it fits, the buttons stay off and the row is just a flex line.
Don't	Hide the buttons and the edge fade together when the row overflows. One of them has to show that more content is off to the side.

Examples

Carousel — Cards

Browse features

Design SystemTokens, components, and patterns

DocumentationAPI reference and usage guides

SandboxVisual testing and previews

LibraryComponent and hook information

ContributingOpen source development

A horizontally scrollable row of cards with snap scrolling enabled. Use for feature grids, product lists, or any set of cards that overflows the available width. The carousel adds fade edges and navigation buttons automatically.

Carousel — Snap

Team members

AC

Alice ChenEngineering Lead

BS

Bob SmithProduct Designer

CD

Carol DavisProduct Manager

AT

Andrew ThomasDesign Manager

GW

Gina WilsonSoftware Engineer

Scroll-snap carousel with navigation buttons and team member cards. Each card snaps to the start edge on scroll. Use when items should be viewed one at a time rather than as a continuous strip.