Skip to content
Pelatform UI

Data display

Carousel

A row of slides on a native scroll-snap track, with previous and next buttons and indicators.

Class nameTypeDescription
carouselplf:carouselComponentA row of slides with its controls
carousel-viewportplf:carousel-viewportPartThe track and its overlaid buttons
carousel-trackplf:carousel-trackPartThe scroll-snap row of slides
carousel-itemplf:carousel-itemPartA slide
carousel-mediaplf:carousel-mediaPartAn image cropped to 16:9
carousel-controlplf:carousel-controlPartA round icon button
carousel-iconplf:carousel-iconPartYour own SVG: the play button's, or one in place of a drawn chevron; an icon class there doesn't need it
carousel-footerplf:carousel-footerPartThe row below the slides
carousel-indicatorsplf:carousel-indicatorsPartHolds the generated indicators
carousel-control-previousplf:carousel-control-previousModifierThe previous button, at the start
carousel-control-nextplf:carousel-control-nextModifierThe next button, at the end
carousel-control-playplf:carousel-control-playModifierA quiet play and pause button

Default

Name the carousel and both buttons, and author the buttons and indicators hidden: without JavaScript the track stays a plain scroller.

A palm tree on a sunny beach
Pine trees below green hills
City towers at sunset

Slides per view

Put the buttons in the footer, after the indicators, so they do not cover the slides.

Plain HTML first

Components start from semantic markup and native behavior.

Guide

Scoped by default

Every rule lives inside a root wrapper.

Architecture

Tokens you can override

Change colors, radii and spacing from a root or one element.

Theming

Full or Modular

Load one bundle or only the components a page needs.

Setup

Right-to-left ready

Logical properties mirror layouts without extra classes.

Guide

Accessible states

Native and ARIA states drive the styles, not extra classes.

Accessibility

Autoplay

Autoplay needs the play button, the way to stop the motion, and starts paused when the user prefers reduced motion.

A palm tree on a sunny beach
Pine trees below green hills
City towers at sunset

JavaScript

Carousel needs JavaScript. The Full script (pelatform-ui.min.js) starts every component on page load, with no code of your own; with ESM imports, call init() yourself, as in Installation. For markup you add later, see Dynamic content.

<link rel="stylesheet" href="pelatform-ui.min.css">
<link rel="stylesheet" href="icons/icons.min.css">
<script src="pelatform-ui.min.js" defer></script>
<link rel="stylesheet" href="pelatform-ui.prefixed.min.css">
<link rel="stylesheet" href="icons/icons.prefixed.min.css">
<script src="pelatform-ui.min.js" defer></script>

Hooks

Attribute Purpose
data-plf-carousel Marks the carousel, named with aria-label or aria-labelledby
data-plf-carousel-track Marks the track, with tabindex="0"; its children, at least two, are the slides
data-plf-carousel-slide Optional on the slides; once one slide has it, every slide needs it
data-plf-carousel-previous, data-plf-carousel-next Mark the <button> controls, authored hidden; unnamed, they are named Previous slide and Next slide
data-plf-carousel-indicators Marks an optional container for the generated indicators, authored hidden; unnamed, it is named Choose slide
data-plf-autoplay The interval in milliseconds, at least 1000; rotation holds on hover and focus and stops when the user navigates
data-plf-carousel-play Marks the play <button>, required with autoplay and authored hidden
data-plf-carousel-icon Optional: pause or play on each icon in the play button; otherwise its first icon is pause and its second play
data-plf-slide-label On the carousel, names slides that have no name; {index} of {count} by default
data-plf-indicator-label Indicator names; Go to slide {index} by default
data-plf-pause-label, data-plf-play-label Play button names; Stop automatic slide show and Start automatic slide show by default
data-plf-previous-label, data-plf-next-label, data-plf-indicators-label On the carousel, names for unnamed controls; Previous slide, Next slide and Choose slide by default

Methods

Method Behavior
PLF.Carousel.getOrCreateInstance(element) Returns the instance, creating it for valid markup
PLF.Carousel.getInstance(element) Returns the instance or null
instance.goTo(index) Scrolls to a stop, counted from 0
instance.next(), instance.previous() Scroll one stop, without wrapping
instance.play(), instance.pause() Start or pause autoplay, on a carousel with data-plf-autoplay
instance.getState() Returns {index, count, playing}
instance.destroy() Stops autoplay and removes listeners, indicators and added attributes

Events

Event When
plf:carousel:change After scrolling settles on a new stop

The event’s detail:

Property Value
instance The Carousel instance
index The new stop, counted from 0
previous The stop before, counted from 0
slide The first slide of the stop
reason previous, next, indicator, keyboard, autoplay, api or scroll

Keyboard

Key Action
Left Arrow, Right Arrow Move one stop from the track, the previous or next button or an indicator; mirrored right to left
Home, End Go to the first or last stop
Tab, Shift+Tab Move between the track, the buttons and the indicators
Enter, Space Activate the focused button or indicator

React

Carousel from @pelatform/react renders this carousel with the runtime’s controls, keyboard, indicators and autoplay: it keeps its own stop, or the application sets it with index, and each part is a component of its own.

Prop Values Default
index The stop shown, from 0, which the application changes in onIndexChange; the carousel scrolls to it, and back to it when the application keeps it Its own state
defaultIndex The stop shown first, when the application does not set index 0
onIndexChange (index, reason), called once scrolling settles on another stop; reason is previous, next, indicator, keyboard, autoplay or scroll None
perView Slides per view, such as 3 or 1.5; it sets --plf-carousel-per-view 1
autoplay The interval in milliseconds, at least 1000, with a CarouselPlay None
Part Element
CarouselViewport A div with carousel-viewport
CarouselTrack A div with carousel-track and tabindex="0", whose children are the slides; slideLabel, (slide, count) => name, names them, {slide} of {count} by default
CarouselItem A div with carousel-item, a slide
CarouselPrevious, CarouselNext A button with carousel-control, type="button", named Previous slide or Next slide unless given an aria-label
CarouselPlay A button with carousel-control-play, type="button", around two icons: the first shows while the slides rotate, the second while they are paused; pauseLabel and playLabel replace its names
CarouselFooter A div with carousel-footer
CarouselIndicators A div with carousel-indicators that renders one indicator per stop, named Choose slide unless given an aria-label; indicatorLabel, (slide, count) => name, names each indicator, Go to slide {slide} by default

The other props are the element’s own, className and ref included; your image takes carousel-media.

CSS variables

Override on a root or on a single carousel.

Variable Default
--plf-carousel-per-view 1
--plf-carousel-slide-min-size 0px
--plf-carousel-gap Space 4 (16px)
--plf-carousel-radius Extra large radius (12px)
--plf-carousel-media-ratio 16 / 9

Built with Pelatform UIv0.1.0

Components

Getting started

Foundations

Components

Actions

Data display

Navigation

Feedback

Data input

Layout

Advanced

Integrations

Blocks

Application

Authentication

Icons