Carousel

Slideshow region with previous and next controls, optional indicators, keyboard, and swipe.

Introduction

Carousel is a slideshow region. Previous and next sit beside the viewport (above and below when vertical), with optional dot indicators, keyboard, and swipe. Slide content stays in the app (CarouselSlide).

One slide fills the viewport by default. slidesPerView shows more than one, including a fraction that peeks the next slide. orientation switches the scroll axis. gap is the space between slides, in px.

When to use: A sequence of peer slides in one viewport — product photos, highlights, stories.

Compared to similar components:

• Tabs — Named peer views that stay on the page. Prefer Tabs when each view has a label the user should see. Use Carousel when the content is a sequence you move through.
• Pagination — Changes which page of a list is shown. Prefer Pagination for data sets. Use Carousel for a track of slides.
• Stepper — Named stages in a process. Prefer Stepper for checkout and wizards.

Use the framework selector in the site header to switch between React and Vue.

Import

import { Carousel } from "@bridge-ui/vue/Components/Carousel";
import { CarouselSlide } from "@bridge-ui/vue/Components/CarouselSlide";

import { Carousel } from "@bridge-ui/react/Components/Carousel";
import { CarouselSlide } from "@bridge-ui/react/Components/CarouselSlide";

Basic usage

Pass an aria-label when the page has more than one carousel, or when a specific name helps. The default label is “Carousel”.

Controlled index

Bind the 0-based snap with index / onIndexChange (React) or v-model:index (Vue). loop wraps from the last snap to the first and back. Without it, the edge control is disabled.

Auto-play

autoPlay accepts true (5 seconds) or an interval in milliseconds. Advance pauses while the pointer is over the carousel, while focus is inside it, and when the user prefers reduced motion.

Several slides

slidesPerView is how many slides fit in the viewport. Values above 1 reveal neighbors; a fraction peeks the next slide. gap is the space between slides, in px.

Each dot is a snap, not a slide. Five slides with slidesPerView={3} show three dots. When every slide fits, the dots stay hidden. With slidesPerView above 1, next stops once the last slides fill the viewport.

Vertical

Set orientation="vertical" to scroll on the vertical axis. The default viewport height comes from size. Set a height on the region when the slides should use a different one.

Sizes

size scales the controls and indicators. Available sizes: sm, md (default), and lg.

Controls and indicators

slots.prev and slots.next replace the chevrons (Vue: #prev and #next). slots.indicator replaces the dot content; the button stays in place. Set indicators to false to hide the dots.

dir="rtl" flips the horizontal axis: arrow keys, swipe, and the track. The chevrons rotate with the direction.

Keyboard and touch

• Horizontal: ArrowLeft / ArrowRight. Vertical: ArrowUp / ArrowDown. dir="rtl" swaps the horizontal arrows.
• Home / End jump to the first and last snap.
• A swipe along the scroll axis moves one snap. The cross-axis is left to the page.
• loop wraps the ends. Without it, the edge control is disabled.
• With slidesPerView above 1, next stops once the last slides fill the viewport.

Accessibility

• The root is a region with aria-roledescription="carousel". Pass aria-label when the default “Carousel” label is too generic.
• Previous and next are named “Previous slide” and “Next slide” through the i18n adapter.
• Each indicator is named Go to slide {index}. The active indicator sets aria-current="true".
• The viewport is a group labelled “Slides”.
• A polite live region announces the active slide.

Anatomy

<section> <!-- root, role="region" -->
  <div> <!-- frame -->
    <div> <!-- viewport, role="group" -->
      <div> <!-- track -->
        <div> <!-- CarouselSlide -->
    <div> <!-- controls -->
      <button> <!-- prev -->
      <button> <!-- next -->
  <div> <!-- indicators -->
    <button> <!-- indicator -->
  <div> <!-- live, aria-live="polite" -->
</section>

Target parts with classes and customProps: root, viewport, track, slide, controls, control, prev, next, indicators, indicator, and live.

Related components

Tabs, Pagination, Stepper

API

Carousel

CarouselSlide