v0.1.0

Appearance

Carousel <l-carousel> ​

Carousels are used to cycle through a set of content slides in a horizontal scrollable area. Commonly used for image galleries, product showcases, and featured content. Powered by Embla Carousel.

HTML tag<l-carousel>
⏣Native HTML
⬡Progressive
◇Custom
⬢Shadow DOM
Custom Element · Shadow DOM

Options ​

Basic ​

Slides are <l-carousel-item> children. Set --slide-size and --slide-gap to control layout. Add drag-free for momentum scrolling.

1
2
3
4
5
6
7
8
9
10
Code
html
<l-carousel
  drag-free
  style="--slide-size: calc(100% / 3); --slide-gap: 1rem"
>
  <l-carousel-item>
    <div
      class="grid place-items-center w-full text-2xl bg-gray-300"
      style="height: 200px"
    >
      1
    </div>
  </l-carousel-item>
  <l-carousel-item>
    <div
      class="grid place-items-center w-full text-2xl bg-gray-300"
      style="height: 200px"
    >
      2
    </div>
  </l-carousel-item>
  <l-carousel-item>
    <div
      class="grid place-items-center w-full text-2xl bg-gray-300"
      style="height: 200px"
    >
      3
    </div>
  </l-carousel-item>
  <l-carousel-item>
    <div
      class="grid place-items-center w-full text-2xl bg-gray-300"
      style="height: 200px"
    >
      4
    </div>
  </l-carousel-item>
  <l-carousel-item>
    <div
      class="grid place-items-center w-full text-2xl bg-gray-300"
      style="height: 200px"
    >
      5
    </div>
  </l-carousel-item>
  <l-carousel-item>
    <div
      class="grid place-items-center w-full text-2xl bg-gray-300"
      style="height: 200px"
    >
      6
    </div>
  </l-carousel-item>
  <l-carousel-item>
    <div
      class="grid place-items-center w-full text-2xl bg-gray-300"
      style="height: 200px"
    >
      7
    </div>
  </l-carousel-item>
  <l-carousel-item>
    <div
      class="grid place-items-center w-full text-2xl bg-gray-300"
      style="height: 200px"
    >
      8
    </div>
  </l-carousel-item>
  <l-carousel-item>
    <div
      class="grid place-items-center w-full text-2xl bg-gray-300"
      style="height: 200px"
    >
      9
    </div>
  </l-carousel-item>
  <l-carousel-item>
    <div
      class="grid place-items-center w-full text-2xl bg-gray-300"
      style="height: 200px"
    >
      10
    </div>
  </l-carousel-item>
</l-carousel>

Add single for one slide at a time.

Code
html
<div class="p-8">
  <l-carousel
    class="w-[400px]"
    single
    style="--slide-size: 100%; --slide-gap: 0"
  >
    <l-carousel-item>
      <img
        class="object-cover"
        src="https://picsum.photos/id/10/1200/700"
        width="400"
        height="400"
        style="height: 400px; max-width: none"
      />
    </l-carousel-item>
    <l-carousel-item>
      <img
        class="object-cover"
        src="https://picsum.photos/id/11/1200/700"
        width="400"
        height="400"
        style="height: 400px; max-width: none"
      />
    </l-carousel-item>
    <l-carousel-item>
      <img
        class="object-cover"
        src="https://picsum.photos/id/12/1200/700"
        width="400"
        height="400"
        style="height: 400px; max-width: none"
      />
    </l-carousel-item>
  </l-carousel>
</div>

Dots (bar) ​

Add with-dots for dot navigation. Default appearance is bar.

Code
html
<l-carousel
  single
  with-dots
>
  <l-carousel-item>
    <img
      class="object-cover w-full h-96"
      src="https://picsum.photos/id/17/1200/700"
      height="400"
    />
  </l-carousel-item>
  <l-carousel-item>
    <img
      class="object-cover w-full h-96"
      src="https://picsum.photos/id/18/1200/700"
      height="400"
    />
  </l-carousel-item>
  <l-carousel-item>
    <img
      class="object-cover w-full h-96"
      src="https://picsum.photos/id/19/1200/700"
      height="400"
    />
  </l-carousel-item>
</l-carousel>

Dots (circle) ​

Set dot-appearance="circle" for circle dots.

Code
html
<l-carousel
  single
  with-dots
  dot-appearance="circle"
>
  <l-carousel-item>
    <img
      class="object-cover w-full h-96"
      src="https://picsum.photos/id/17/1200/700"
      height="400"
    />
  </l-carousel-item>
  <l-carousel-item>
    <img
      class="object-cover w-full h-96"
      src="https://picsum.photos/id/18/1200/700"
      height="400"
    />
  </l-carousel-item>
  <l-carousel-item>
    <img
      class="object-cover w-full h-96"
      src="https://picsum.photos/id/19/1200/700"
      height="400"
    />
  </l-carousel-item>
</l-carousel>

Breakpoints ​

Use the breakpoints attribute (JSON) to override options at specific breakpoints. The carousel can deactivate itself at wider viewports.

Code
html
<style>
  .carousel-breakpoints {
    --slide-size: 80%;
    --slide-gap: 1rem;
    --button-border-color: #d3c9c9;
    height: 400px;
  }
  @media (min-width: 768px) {
    .carousel-breakpoints {
      --slide-size: 33%;
      --slide-gap: 1rem;
    }
  }
</style>
<l-carousel
  class="carousel-breakpoints"
  breakpoints='{"(min-width: 768px)": { "active": false }}'
>
  <l-carousel-item>
    <img
      class="object-cover"
      src="https://picsum.photos/id/17/1200/700"
      width="400"
      height="400"
      style="height: 400px"
    />
  </l-carousel-item>
  <l-carousel-item>
    <img
      class="object-cover"
      src="https://picsum.photos/id/18/1200/700"
      width="400"
      height="400"
      style="height: 400px"
    />
  </l-carousel-item>
  <l-carousel-item>
    <img
      class="object-cover"
      src="https://picsum.photos/id/19/1200/700"
      width="400"
      height="400"
      style="height: 400px"
    />
  </l-carousel-item>
</l-carousel>

Autoplay ​

Set autoplay to a delay in milliseconds. Combine with axis="y" for vertical rotation.

Free shipping on orders over $80
4.9/5 (47 reviews) — Read reviews
Code
html
<l-carousel
  axis="y"
  autoplay="10000"
  duration="5"
  style="
    --slide-height: 36px;
    --button-size: 24px;
    --button-bg: transparent;
    --button-border-color: transparent;
    --button-arrow-color: white;
  "
>
  <l-carousel-item>
    <div
      class="py-2 px-4 lg:px-8 bg-gradient-to-r from-red-600 to-red-500 text-white font-bold text-center text-sm w-full whitespace-nowrap overflow-x-auto"
    >
      Free shipping on orders over $80
    </div>
  </l-carousel-item>
  <l-carousel-item>
    <div
      class="py-2 px-4 lg:px-8 bg-gradient-to-r from-red-600 to-red-500 text-white font-bold text-center text-sm w-full whitespace-nowrap overflow-x-auto"
    >
      4.9/5 (47 reviews) — Read reviews
    </div>
  </l-carousel-item>
</l-carousel>

Examples ​

Single slide with dots and fullscreen button.

Code
html
<l-carousel
  single
  with-dots
  with-fullscreen
>
  <l-carousel-item>
    <img
      class="object-cover w-full h-96"
      src="https://picsum.photos/id/20/1200/700"
      height="400"
    />
  </l-carousel-item>
  <l-carousel-item>
    <img
      class="object-cover w-full h-96"
      src="https://picsum.photos/id/21/1200/700"
      height="400"
    />
  </l-carousel-item>
  <l-carousel-item>
    <img
      class="object-cover w-full h-96"
      src="https://picsum.photos/id/22/1200/700"
      height="400"
    />
  </l-carousel-item>
</l-carousel>

Product grid with scrollbar ​

Drag-free with scrollbar and outside navigation buttons.

Code
html
<l-carousel
  drag-free
  with-scrollbar
  scroll-buttons-position="outside"
  style="--slide-size: calc(100% / 3); --slide-gap: 1rem"
>
  <l-carousel-item>
    <img
      class="object-cover w-full h-96"
      src="https://picsum.photos/id/30/1200/700"
      height="400"
    />
  </l-carousel-item>
  <l-carousel-item>
    <img
      class="object-cover w-full h-96"
      src="https://picsum.photos/id/31/1200/700"
      height="400"
    />
  </l-carousel-item>
  <l-carousel-item>
    <img
      class="object-cover w-full h-96"
      src="https://picsum.photos/id/32/1200/700"
      height="400"
    />
  </l-carousel-item>
  <l-carousel-item>
    <img
      class="object-cover w-full h-96"
      src="https://picsum.photos/id/33/1200/700"
      height="400"
    />
  </l-carousel-item>
  <l-carousel-item>
    <img
      class="object-cover w-full h-96"
      src="https://picsum.photos/id/34/1200/700"
      height="400"
    />
  </l-carousel-item>
  <l-carousel-item>
    <img
      class="object-cover w-full h-96"
      src="https://picsum.photos/id/35/1200/700"
      height="400"
    />
  </l-carousel-item>
  <l-carousel-item>
    <img
      class="object-cover w-full h-96"
      src="https://picsum.photos/id/36/1200/700"
      height="400"
    />
  </l-carousel-item>
  <l-carousel-item>
    <img
      class="object-cover w-full h-96"
      src="https://picsum.photos/id/37/1200/700"
      height="400"
    />
  </l-carousel-item>
  <l-carousel-item>
    <img
      class="object-cover w-full h-96"
      src="https://picsum.photos/id/38/1200/700"
      height="400"
    />
  </l-carousel-item>
  <l-carousel-item>
    <img
      class="object-cover w-full h-96"
      src="https://picsum.photos/id/39/1200/700"
      height="400"
    />
  </l-carousel-item>
</l-carousel>

Accessibility ​

Criteria ​

Role

Each <l-carousel-item> has role="group"

WCAG4.1.2
Dot navigation

Dots use role="tab" with aria-label and aria-selected

WCAG4.1.2
Disabled buttons

Previous/next buttons are disabled when at scroll boundaries

WCAG4.1.2

Keyboard interactions ​

Tab
Moves focus between navigation buttons
Enter
Activates the focused button (next, previous, or dot)
Space
Activates the focused button

API reference ​

Importing ​

js
import 'luxen-ui/carousel';
import 'luxen-ui/carousel-item';

Attributes & Properties ​

autoplayAttribute
Autoplay delay in milliseconds. 0 disables autoplay
autoplay-optionsAttribute
Embla autoplay plugin options (JSON object)
axisAttribute
Scroll axis: x (default) or y
alignAttribute
Slide alignment: start (default), center, end
breakpointsAttribute
Breakpoint-specific option overrides (JSON object)
loopAttribute
Enable infinite looping
drag-freeAttribute
Enable momentum scrolling
durationAttribute
Scroll animation duration. Default 20
skip-snapsAttribute
Allow skipping snap points on vigorous drag
slides-to-scrollAttribute
Number of slides per scroll group. Default 1
start-indexAttribute
Initial scroll snap index. Default 0
contain-scrollAttribute
Trim empty space: trimSnaps (default) or keepSnaps
singleAttribute
Show one slide at a time
with-dotsAttribute
Show dot navigation
with-scrollbarAttribute
Show native scrollbar on viewport
with-fullscreenAttribute
Show fullscreen button
dot-appearanceAttribute
Dot style: bar (default) or circle
scroll-buttons-positionAttribute
Button position: inside (default) or outside

Methods ​

next()Method
Scroll to the next slide
previous()Method
Scroll to the previous slide
goToSlide(index, jump?)Method
Scroll to a specific slide index
isActive()Method
Returns whether the carousel is active

Events ​

selectEvent
Fired when the selected slide changes. Detail: { index }
slides-in-viewEvent
Fired when visible slides change. Detail: { indexes }
fullscreenEvent
Fired when the fullscreen button is clicked

CSS Parts ​

viewportPart
The overflow container
containerPart
The slides slot
scroll-buttonsPart
Previous/next button wrapper
buttonPart
Any navigation button
button-previousPart
The previous button
button-nextPart
The next button
button-dotPart
A dot navigation button
button-fullscreenPart
The fullscreen button
button-iconPart
Any button icon SVG
dotsPart
The dots container

CSS custom properties ​

--slide-heightName
Slide height for vertical axis mode. Default 19rem
--slide-sizeName
Slide width (flex-basis). Default 100%
--slide-gapName
Gap between slides. Default 0
--button-sizeName
Navigation button size. Default 48px
--button-arrow-sizeName
Arrow icon size. Default 20px
--button-arrow-colorName
Arrow icon color
--button-offsetName
Inside-positioned button offset. Default 8px
--button-border-colorName
Button border color
--button-border-radiusName
Button border radius. Default 8px
--button-bgName
Button background color
--button-colorName
Button text/icon color
--dot-colorName
Inactive dot color
--dot-color-activeName
Active dot color
--dot-marginName
Dot container margin. Default 0.5rem 0
roleAttribute
Automatically set to group
--aspect-ratioName
Aspect ratio of the slide. Default inherit