Carousel

A scrollable list with snap-aligned slides and optional previous/next buttons.

Usage

Load the styles and scripts

Load a Basecoat style bundle and the Basecoat runtime with carousel.js, or use the full JavaScript bundle. See Installation.

<script src="/assets/js/basecoat.min.js" defer></script>
<script src="/assets/js/carousel.min.js" defer></script>

Add slides and controls

Use a .carousel root, a direct child <ul>, and <li> slides. Add scrollbar to the list for a themed scrollbar and tabindex="0" so keyboard users can scroll it. Native scrolling, touch gestures, and snapping work without JavaScript. Style packs give slides padding to leave room for card shadows; use padding utilities on the <li> to customize it.

<div class="carousel" role="region" aria-roledescription="carousel" aria-label="Featured items">
  <ul role="list" class="scrollbar" tabindex="0" aria-label="Slides">
    <li>First slide</li>
    <li>Second slide</li>
    <li>Third slide</li>
  </ul>
  <button type="button" class="btn" data-variant="outline" hidden>Previous</button>
  <button type="button" class="btn" data-variant="outline" hidden>Next</button>
</div>

The two optional buttons are direct children: Previous first, then Next. Keep them hidden until the script initializes. The script scrolls to the next slide’s start and disables buttons at the ends. It also updates when slides are added, removed, or resized. Position the buttons with utilities, as in the preview.

Unlike upstream’s Embla carousel, this uses browser scrolling. It does not provide looping, autoplay, mouse-drag handling, or Embla’s plugin/API system. Touch and trackpad scrolling remain native. Smooth scrolling respects reduced-motion preferences.

Arrow keys work when the list or a previous/next button has focus, respecting orientation and RTL. Keys inside slide content are left alone. When a focused control becomes disabled at an end, focus moves to the other control (or the list if neither can scroll).

Slides intentionally keep native list semantics instead of upstream’s ARIA slide groups. role="list" preserves those semantics in browsers that otherwise omit unstyled lists from the accessibility tree. Real buttons share Basecoat Button styles across themes; their shape follows the style pack: fully round in Vega, Nova, Maia, Mira, and Luma; rounded-2xl in Rhea; and the ordinary Button shape in Lyra and Sera. The script enhances native scrolling rather than using CSS-generated scroll buttons and maintaining a second fallback control system.

Examples

Sizes

Use basis-* utilities on each slide to show multiple items. This example shows two items, or three at large widths. Subtract the list’s gaps when calculating each slide’s basis so the visible cards fit completely.

Spacing

Use a normal gap utility on the list and account for it in each slide’s basis. This example uses gap-1, matching upstream’s smaller spacing.

Orientation

Set data-orientation="vertical" and give the list a fixed height. Center the buttons with inset-x-0 mx-auto in either text direction. Subtract the gap from the available height before dividing it between two slides: basis-[calc((100%_-_0.25rem)/2)] with gap-1. This keeps both cards fully visible, including at the end.

Without buttons

Omit the buttons and JavaScript when native scrolling is sufficient. Add scrollbar to the <ul> to reuse Scroll Area’s themed scrollbar. Keep the list keyboard-focusable; touch and trackpad gestures also scroll it. Carousel hides the scrollbar once its previous/next controls initialize. This native scrolling fallback is an intentional addition to upstream’s button-driven carousel.

RTL

Set dir="rtl" on the carousel or an ancestor. Logical positioning utilities place the controls correctly; flip horizontal arrow icons to match the reading direction.