Carousel

Carousels cycle through a set of panels (hero images, feature highlights, or onboarding steps). index is the first visible slide; slidesPerView controls how many fill the viewport.

Try it

Usage

Place RuiCarouselSlide children inside RuiCarousel. Each slide needs an id. Enable autoplay only when motion is not distracting and can be paused.

import { RuiCarousel, RuiCarouselSlide } from '@ecopages/radiant-ui/carousel';
 
<RuiCarousel index={0} transition="slide" showIndicators label="Feature highlights">
  <RuiCarouselSlide id="first">First panel</RuiCarouselSlide>
  <RuiCarouselSlide id="second">Second panel</RuiCarouselSlide>
</RuiCarousel>Copy

Custom markup

<rui-carousel> coordinates any light-DOM tree that matches its query contract. The Rui* helpers stamp these targets; they are not required.

import '@ecopages/radiant-ui/carousel';
 
<rui-carousel index={0} transition="slide" slides-per-view={3} show-indicators label="Feature highlights">
  <section data-ref="root" class="rui-carousel rui-carousel--slide" data-carousel-track="window" data-carousel-surface="cards" aria-roledescription="carousel" aria-label="Feature highlights">
    <div class="rui-carousel__stage">
      <div data-ref="viewport" class="rui-carousel__viewport">
        <div data-ref="track" class="rui-carousel__track">
          <div data-slide="first" class="rui-carousel__slide">First panel</div>
          <div data-slide="second" class="rui-carousel__slide">Second panel</div>
          <div data-slide="third" class="rui-carousel__slide">Third panel</div>
        </div>
      </div>
    </div>
    <div class="rui-carousel__footer">
      <button type="button" data-carousel-action="prev">Previous</button>
      <div data-ref="indicators" role="group" aria-label="Choose slide window"></div>
      <button type="button" data-carousel-action="next">Next</button>
    </div>
  </section>
</rui-carousel>Copy

When show-indicators is set, the host creates [data-carousel-indicator] buttons inside [data-ref="indicators"]. One slide per view uses a tab for each slide. Multiple slides per view use one button per valid window start, with aria-current identifying the current window. Five slides with slidesPerView={3} have three window buttons. Arrow keys, Home, and End navigate those windows.

Show several slides

Set slidesPerView to how many slides fill the viewport (1.2 peeks the next slide at the start, and the previous slide at the end so the last full card sits on the right). slidesPerGroup is how far prev/next/autoplay move. index stays the first visible slide. One pane keeps chrome on the viewport; more than one slide paints each slide as a card. Space between cards is --rui-carousel-gap (default --space-inline):

rui-carousel {
  --rui-carousel-gap: 1.5rem;
}Copy

<RuiCarousel transition="slide" slidesPerView={3} slidesPerGroup={3} label="Featured products">
  <RuiCarouselSlide id="one">One</RuiCarouselSlide>
  <RuiCarouselSlide id="two">Two</RuiCarouselSlide>
  <RuiCarouselSlide id="three">Three</RuiCarouselSlide>
  <RuiCarouselSlide id="four">Four</RuiCarouselSlide>
  <RuiCarouselSlide id="five">Five</RuiCarouselSlide>
  <RuiCarouselSlide id="six">Six</RuiCarouselSlide>
</RuiCarousel>Copy

Use autoplay sparingly

Autoplaying carousels can disorient users and violate reduced-motion preferences. Prefer manual controls and expose showRotationControl when autoplay is on.

Pick a transition

slide moves content horizontally. fade cross-fades panels. none swaps instantly and is best when motion would be gratuitous.

Set controlsVariant="overlay" to pin prev/next on the slide edges.

Theming

Carousel maps to semantic surface and border roles, never Tailwind palette steps:

Override the --rui-carousel-* custom properties on rui-carousel. Theme roles stay the defaults behind those properties.

API

RuiCarousel is a custom element (<rui-carousel>) that owns slide state, autoplay, transitions, and control chrome. The RuiCarouselSlide and control helpers compose the surface. index is the first visible slide.

Attributes

CSS properties

Set these on rui-carousel. Each defaults to a theme token.

Light-DOM contract

Do not set aria-hidden, aria-selected, or tabIndex on slides or indicators. Nested hosts: none.

View helpers

CSS classes

Public BEM classes (documented via @cssclass on the element and view helpers):

Theme roles

Accessibility

• Provide a descriptive label so screen readers identify the carousel region.
• Prev/next controls must be keyboard reachable and expose their purpose in the accessible name.
• Slides outside the visible window are aria-hidden. data-active marks the first visible slide.
• Respect prefers-reduced-motion and avoid autoplay when users request reduced motion.