Carousel

Styles live in scss/components/_carousel.scss. Combine slide content (your markup) with .carousel controls; the live demos below show two compositions plus the control primitives.

Anatomy

Prerequisites

• PimentCSS installed, Installation.
• Icons, ph-arrow-right at 24px via ph() (Phosphor in this doc).
• Slides, any HTML (image, text, cards); keep one visible slide at a time.
• Script, call wireAllCarousels() after DOM ready (see interactive section).

Composed carousels (live)

Two widget patterns share the same .carousel controls. Use arrow keys on the carousel region or the scroll bar (slider). Status text updates in aria-live="polite".

Media + text

Split layout from min-width: 30rem: visual block + title and body copy. Decorative gradients use role="img" and a text alternative.

Text-only slides

Same controls and behavior without a media column. Useful for quotes, KPIs, or legal notices.

<div class="pdoc-carousel-widget" data-carousel-live="" role="region" aria-roledescription="carousel" aria-label="Featured topics" tabindex="-1">
  <div class="pdoc-carousel-widget__viewport">
    <article class="pdoc-carousel-widget__slide" data-carousel-slide="" role="group" aria-roledescription="slide" aria-label="1 of 3: Accessible forms">
      <div class="pdoc-carousel-widget__media" role="img" aria-label="…"></div>
      <div class="pdoc-carousel-widget__body">
        <h3 class="pdoc-carousel-widget__title">Accessible forms</h3>
        <p class="pdoc-carousel-widget__text">…</p>
      </div>
    </article>
  </div>
  <p data-carousel-status="" aria-live="polite">Slide 1 of 3: Accessible forms</p>
  <div class="carousel pdoc-carousel-widget__controls">…</div>
</div>

Arrow primitives

48px circular buttons with a 2px action border. Doc-only .carousel__arrow--hover and .carousel__arrow--focus; production uses :hover and :focus-visible.

Scroll bar primitives

The scroll bar is a role="slider" when it reflects slide position (aria-valuenow, aria-valuemin, aria-valuemax). Default height is 2px; it grows to 4px on :hover. Use the interactive lab first, then compare the static state references below.

Static references (doc-only modifiers for focus/hover height previews):

Controls only

Use when slide content lives elsewhere (for example a full-width hero). Mark a decorative bar with aria-hidden="true".

JavaScript

Add data-carousel-live on .pdoc-carousel-widget (full carousel) or data-carousel-scrollbar-live on .pdoc-carousel-scrollbar-lab (scroll bar only). Call wireAllCarousels() after load.

import { wireAllCarousels } from './carousel-behavior';

document.addEventListener('DOMContentLoaded', () => wireAllCarousels());

// Full widget: .pdoc-carousel-widget[data-carousel-live] + [data-carousel-slide]
// Scroll bar lab: .pdoc-carousel-scrollbar-lab[data-carousel-scrollbar-live]

Class reference

Customize (Sass)

1. 01

   Carousel sizing

   Override max width, gaps, arrow size, and scroll bar metrics.
   variables

   @use "pimentcss-design-system" with (
     $carousel-max-width: 40rem,
     $carousel-gap: 1rem,
     $carousel-arrow-size: 3rem,
     $carousel-scrollbar-thumb-width: 37.5%
   );

2. 02

   Rebuild CSS

   Run after editing _carousel.scss.
   Terminal

   npm run build:css

Accessibility (RGAA / WCAG)

Next steps