EOS UICarousel
A framework-agnostic Web Component for cycling through content with navigation, indicators, autoplay, and touch gestures.
Import
import '@eosjs/ui/carousel';Introduction
Carousel presents a sequence of slides with native keyboard navigation, touch gestures, optional autoplay, and clickable progress indicators. Slides are passed through the default slot, so each slide can contain any HTML or Web Component content.
When the operating system requests reduced motion, autoplay stays paused and slide transitions become effectively instant. Manual navigation remains available.
Basic Usage
Basic usage
API
Generated from custom-elements.json for eos-carousel.
Attributes
| Name | Type | Default | Description |
|---|---|---|---|
autoplay | — | — | — |
interval | — | — | — |
loop | — | — | — |
show-navigation | — | — | — |
initial-index | — | — | — |
indicator-position | — | — | — |
indicator-style | — | — | — |
virtual-threshold | — | — | — |
Events
| Name | Type | Description |
|---|---|---|
slide-active | CustomEvent | — |
slide-click | CustomEvent | — |
change | CustomEvent | — |
Methods
| Name | Signature | Description |
|---|---|---|
next | — | — |
prev | — | — |
goTo | — | — |
play | — | — |
setSlideLoading | — | 设置当前 slide 为加载中状态（波纹动画） 调用 startSlideProgress 时会自动结束加载状态 |
startSlideProgress | — | 开始当前 slide 的进度倒计时 |
stopSlideProgress | — | — |
pauseSlideProgress | — | 暂停当前 slide 的进度并保留已完成的进度 |
resumeSlideProgress | — | 恢复当前 slide 从暂停位置继续进度 |
pause | — | — |
updateProgress | — | 手动同步进度显示（用于视频播放进度） |
Attributes
| Attribute | Type | Default | Description |
|---|---|---|---|
autoplay | boolean | false | Automatically advance through the slides |
interval | number | 2000 | Autoplay interval in milliseconds; values below 1000 are clamped |
loop | boolean | false | Continue from the first slide after the last slide |
show-navigation | boolean | true | Show previous and next controls |
initial-index | number | 0 | Initial zero-based slide index |
indicator-position | top | bottom | left | right | bottom | Position of the progress indicators |
indicator-style | default | dots | tiktok | default | Visual style of the progress indicators |
virtual-threshold | number | 8 | Enable three-slot rendering after this many slides |
Events
| Event | When it fires | event.detail |
|---|---|---|
change | The active slide changes | { currentIndex, previousIndex } |
slide-active | A slide becomes active | { index, slide, mediaType } |
slide-click | A slide is clicked | { index } |
Methods
Carousel exposes imperative controls through its DOM element:
const carousel = document.querySelector('eos-carousel');
carousel.play();
carousel.pause();
carousel.next();
carousel.prev();
carousel.goTo(2);Slots
Use the default slot for any slide content:
<eos-carousel autoplay loop interval="3000">
<img src="/cover-01.jpg" alt="Mountain landscape" />
<img src="/cover-02.jpg" alt="Coastal landscape" />
</eos-carousel>CSS custom properties
| Property | Default | Description |
|---|---|---|
--carousel-height | 400px | Height of the carousel host |
--progress-bar-height | 3px | Indicator height in pixels |
--progress-bar-gap | 3px | Gap between indicators |
--progress-bar-color | rgba(255, 255, 255, 0.3) | Inactive indicator color |
--progress-bar-active-color | rgba(255, 255, 255, 1) | Active indicator color |
--control-bg | rgba(0, 0, 0, 0.3) | Navigation control background |
--control-hover-bg | rgba(0, 0, 0, 0.5) | Navigation control hover background |
Framework integration
Carousel is a standard custom element. The same markup works in React, Vue, Angular, and native HTML; framework listeners receive the native DOM and CustomEvent APIs.
<eos-carousel autoplay loop interval="3000">
<div>Slide one</div>
<div>Slide two</div>
</eos-carousel>