Skip to main content

Carousel

shadow

A Carousel is an element that displays multiple items, such as images or news updates, in a rotating fashion.

Basic usage​

This example shows the simplest carousel with several slides and default controls, so the baseline slide-to-slide behavior is easy to understand.

Paginaton​

This example enables pagination controls so you can see how users can move between slides without relying on gestures or arrows.

No loop​

This example disables infinite looping, so the first and last slide behave like real boundaries.

Dialogue​

This example places the carousel inside a dialog to show how it behaves in the constrained space of an overlay.

Thumbnail image​

This example adds thumbnail previews that act as secondary navigation between slides.

Offset​

This example works with spacing between slides and around the viewport so you can compare a tighter and a more airy layout rhythm.

Distribution​

This example splits the available space so that multiple slides stay visible at the same time, which is useful for galleries or dense overviews.

When to use​

Use wje-carousel to improve readability, scannability, and contextual understanding of content.

When not to use​

Do not replace structured interactive data with media-only presentation when precision is needed.

Accessibility​

Provide alt text, maintain readable contrast, and include text equivalents for icon-only controls.

Best Practices​

  • Compress media and use lazy loading in larger collections.
  • Keep information priority consistent across cards/lists.
  • Avoid duplicating the same meaning in icon and text without added value.

Attributes and Properties​

activeSlide​

DescriptionActive slide attribute.
Attributeactive-slide
Typenumber｜number
Default0

continuousLoop​

DescriptionContinuous loop attribute.
Attributecontinuous-loop
Typeboolean
Defaultfalse

loop​

DescriptionControls whether loop is enabled and affects component behavior.
Attributeloop
Typeboolean
Defaultfalse
DescriptionControls whether navigation is enabled and affects component behavior.
Attributenavigation
Typeboolean
Defaultfalse

pagination​

DescriptionControls whether pagination is enabled and affects component behavior.
Attributepagination
Typeboolean
Defaultfalse

slidePerPage​

DescriptionSets the numeric value used for slide-per-page.
Attributeslide-per-page
Typenumber
Default1

thumbnails​

DescriptionControls whether thumbnails is enabled and affects component behavior.
Attributethumbnails
Typeboolean
Defaultfalse

Events​

No events available for this component.

Methods​

syncActiveToSnapStart​

DescriptionSync activeSlide to the slide whose leading edge is closest to the snap start.
Signature() => void

syncSlideMetrics​

DescriptionSyncs computed CSS variables derived from slide-per-page.
Signature() => void

getScrollPaddingInlineStart​

DescriptionReturns the inline scroll padding used by the snap area.
Signature() => number

getControlBehavior​

DescriptionReturns the interaction scroll behavior for UI controls. Continuous multi-slide loops use instant snapping to avoid blank edge states while the browser is still animating a previous smooth scroll.
Signature() => ScrollBehavior｜string

goToSlide​

DescriptionGoes to the slide.
Signature(index: any, behavior: any, next: any) => void

setActiveVisualSlide​

DescriptionSets the active class on the currently targeted visual slide and removes it elsewhere.
Signature(vIndex: number) => void

createLoopClone​

DescriptionCreates a sanitized loop clone that does not inherit transient render state such as inline visibility: hidden from the source slide.
Signature(item: HTMLElement) => HTMLElement

removeLoopClones​

DescriptionRemoves loop clones so they can be rebuilt for the current configuration.
Signature() => void

getLoopCloneCount​

DescriptionReturns how many slides should be cloned on each side when loop is enabled.
Signature(totalSlides: number) => number

scrollToVisualIndex​

DescriptionScrolls the carousel to a visual slide index.
Signature(vIndex: number, behavior: ScrollBehavior｜string) => void

nextSlide​

DescriptionGoes to the next slide.
Signature() => void

previousSlide​

DescriptionGoes to the previous slide.
Signature() => void

getSlides​

DescriptionGoes to the slide.
Signature() => Array

getMaxVisibleStartIndex​

DescriptionReturns the maximum logical slide index that can still render a full viewport.
Signature(totalSlides: number) => number

normalizeLoopIndex​

DescriptionNormalizes a logical index for the active loop mode.
Signature(index: number, totalSlides: number) => number

getLoopLogicalCount​

DescriptionReturns how many logical positions are reachable for the current loop mode.
Signature(totalSlides: number) => number

getPaginationIndexes​

DescriptionReturns the pagination indexes for the current carousel mode.
Signature() => number[]

canGoNext​

DescriptionGoes to the slide.
Signature() => boolean

canGoPrevious​

DescriptionGoes to the slide.
Signature() => boolean

CSS Shadow Parts​

No CSS shadow parts available for this component.

CSS Custom Properties​

NameDescription
--wje-carousel-sizeEffective size of one carousel item.
--wje-carousel-gapGap between carousel items.

Slots​

NameDescription
defaultDefault slot for the main component content.

Content