ESL Carousel

ESLCarousel - a slideshow component for cycling through slides. It supports various types of renderers to choose technical implementation of the carousel. The main part of ESLCarousel is a custom element ESLCarousel (esl-carousel) and custom attribute ESLCarouselSlide (esl-carousel-slide). As well as various renderers, ESLCarousel supports set of mixins-plugins to extend carousel functionality. Almost every carousel parameter is customizable and can be configured using ESLMediaRuleList syntax.

ESLCarousel Structure

As was mentioned above, ESLCarousel consists of esl-carousel custom element and esl-carousel-slide custom attribute. The esl-carousel element does not support any extra content inside (at least the one that is in CSS flow), as it most likely break the carousel layout. The only child of esl-carousel should be esl-carousel-slides container. You can define it manually or skip it, so the esl-carousel will create it during rendering automatically.

The slide elements should be marked with esl-carousel-slide custom attribute (mixin). All slides will maintain their position inside the esl-carousel-slides container. The ESLCarousel does not allow esl-carousel-slide to be placed outside of esl-carousel-slides container.

The folowing example shows the basic structure of ESLCarousel:

<esl-carousel>
  <ul esl-carousel-slides>
    <li esl-carousel-slide>Slide 1</div>
    <li esl-carousel-slide>Slide 2</div>
    <li esl-carousel-slide>Slide 3</div>
  </ul>
</esl-carousel>

As was already mentioned, esl-carousel is restrictive to the structure but the tag names can be customized chosen by the user. Note tht esl-carousel uses divs by default and provides accessibility trough ARIA attributes.

So default ESLCarousel structure will look like this:

<esl-carousel>
  <div esl-carousel-slides>
    <div esl-carousel-slide>Slide 1</div>
    <div esl-carousel-slide>Slide 2</div>
    <div esl-carousel-slide>Slide 3</div>
  </div>
</esl-carousel>

Note ⚠️: we recomend to define esl-carousel-slides tag explicitly in case your contend is not dynamic it will help to avoid Cummutative Layout Shift (CLS) issues and allows content to be properly displayed before ESLCarousel (JS) initialization.

ESLCarousel Root Element API

Carousel configuration usually goes through the ESLCarousel root element attributes/properties. Note that almast all of the basic ESLCarousel attributes/properties are available with ESLMediaRuleList syntax (where it makes sence). Both of the ESLMediaRuleList syntaxes are supported:

Note: a single value attributes will be considered as all-rule so they spreads across all media conditions.

Attributes/Properties

State Attributes (read-only)

State Properties (read-only)

Methods

ESLCarousel Events

ESLCarousel dispatches several custom events to notify about state changes and actions. You can listen to these events on the <esl-carousel> element to react to slide changes, configuration updates, and more.

Slide Change Events

All slide change events use the ESLCarouselSlideEvent class and provide the following useful properties:

Event types:

Carousel Configuration Change Event

The configuration change event uses the ESLCarouselChangeEvent class and provides the following useful properties:

Event types:

For more details, see the event classes in core/esl-carousel.events.ts.

Carousel Move Event

The move event uses the ESLCarouselMoveEvent class and provides the following useful properties:

ESLCarouselSlideTarget type

The ESLCarouselSlideTarget is a number or string that defines the target slide for any function or plugin in the carousel navigation API.

The following nav commands are available:

NOTE: Please be aware of the numbering differences:

ESL Carousel Slide API

As was mentioned previously the ESLCarousel slides should be marked with esl-carousel-slide custom attribute. The mixin behind the esl-carousel-slide attribute also provides some markers to define the slide state.

Attributes (read-only)

Accessibility behavior

The esl-carousel-slide mixin provides the accessibility behavior. The accessibility behavior is based on the following attributes:

ESLCarousel Renderers

You can choose the renderer for the ESLCarousel component trough the type attribute. Diferent type of renderers can be associated with different media condition (see ESLMediaRuleList syntax support). The following renderers are available out of the box:

The default renderer for ESL Carousel. Uses the flexbox layout to display slides. Moves the slides with CSS transitions of the scene transform property. If the loop attribute is set to true, the renderer will reorder the slides with a flexbox order property to create the loop effect. By default try to move half of remaining slides to the opposite side of the carousel if loop is enabled. However, you can forbid this behavior by setting lazy-reorder attribute (which supports ESLMediaQuery syntax), so the renderer will move slide only during the animation. Does not do any DOM manipulations with the slides. Supports the posibility to show multiple slides at once as well as siblings visibility effect (the next and previous slides are partially visible). Supoorst all ESLCarousel attributes and properties including vertical and step-duration.

To fine-tune the layout you can use the following recipes:

  1. Slide size: The carousel renderer defines the --esl-slide-size (readonly) CSS variable with the size of the slide according to the carousel calculations. However, we do not recomend to rely on it to render first slide. It is recommended to define width or height for the slide elements explicitly. You can define width or height in px (absolute value), any media related unit or relativly in %. Default layout makes it possible to use % based sizes for the slides, based on the carousel size (but not the scene size). For examole width: 100% will make the slide to fill the carousel width.
  2. Slide spacing: To define the space between the slides you can just use native flexbox gap property. The renderer is aware of the gap and will adjust the slide size and calculations accordingly.
  3. Transitions: The renderer uses the JavaScript Animation API to animate slides. The only way to customize the transition is by setting the duration via the CSS variable --esl-carousel-step-duration. The carousel renderer reads the computed value of this CSS variable to determine the transition duration. In addition to using the CSS variable directly, you can also specify the step-duration attribute on the <esl-carousel> element. This attribute supports ESLMediaRuleList syntax, including definitions based on media attribute. Technically, the step-duration attribute sets the transition duration CSS variable on the carousel root element during the animation step.
  4. Siblings visibility and overflow: The CSS overflow property is set to clip(or hidden for legacy browsers) on the esl-carousel element to hide out of view slides. However, the start position and calculations are based on esl-carousel-slides container element. You can utilize this to create siblings visibility effect by setting margin to the esl-carousel-slides container. Note that out of the box ESL Carousel already utilizes that trick to set visibility tolerance, you can adjust the out of the box behavior with --esl-carousel-side-space CSS variable as well.
  5. Limit reordering in loop mode (Could be useful to limit CLS issues, when content of the slide is heavy): By default, the renderer will reorder/move a half of the remaining slides to the opposite side of the carousel if loop is enabled. You can forbid this behavior by setting lazy-reorder attribute. It is an ESLMediaQuery, so you can define it for specific media conditions. Note that if you use siblings visibility effect, you will not see the last slide before the first one in the loop mode unless backward animation is playing. However, this option could be useful to limit CLS issues, when content of the slide is heavy (e.g. esl-media with the fill option).

An extension of the default renderer that centers the active slide in the carousel. Does not have any critical configurational or functional differences from the default renderer except the process of offset calculation.

The grid renderer for ESL Carousel is based on the Default renderer but uses the CSS Grid layout to display slides. Unlike the Default renderer, the Grid renderer displays multiple rows (horizontal case) or columns (vertical case) of slides.

Note that the Grid renderer is more restrictive in terms of the slide size definition. Unlike the Default renderer, the Grid renderer does not support relative sizes for the slides (grid layout liitations).

Default CSS Renderer (type: css) new

Uses the ESLCSSCarouselRenderer implementation. This renderer does not apply any JavaScript-based animation logic. It relies entirely on CSS-defined transitions and animations.

Note: This renderer does not listen for specific transition or animation events. Therefore, the animation duration must be explicitly defined using the --esl-carousel-step-duration CSS variable. It is also good practice to use the --esl-carousel-step-duration CSS variable within your animation. This enables duration customization via the step-duration attribute as well.

Animations can make use of global markers such as active, pre-active, next, and prev attributes, as well as the animating state attribute on the carousel element.

Additionally, the renderer provides the CSS classes forward, and backward on [esl-carousels-slides] to help define animation direction.

The renderer supports the move operation, but you must rely on one of the following CSS variables and markers:

By default, this renderer does not include any specific animation. However, several built-in animation implementations are provided (detailed below).

It is important to note that the CSS renderer uses a grid layout for the slides container to ensure consistent slide sizes (auto-height). You need to override the layout intentionally if you want to use a different method to normalize the slide/carousel sizes.

CSS Fade Renderer (type: css-fade)

An extension of the default CSS renderer that provides fade animation styles for slide transitions. Supports move operations relative to the carousel size and move tolerance.

CSS Slide Renderer (type: css-slide)

An extension of the default CSS renderer that provides sliding animation styles for slide transitions. Supports move operations based on absolute pixel offset.

The none renderer for ESL Carousel is a dummy renderer that does not change the slides layout and assumes that all the slides are visible at once. It is useful when you want to 'mute' the carousel behavior for some media conditions. For example, you need the carousel on mobile but want to show all the slides at once on desktop.

ESLCarousel Plugins

The ESLCarousel supports a set of plugins to extend the carousel functionality. The most of plugins are mixins that can be applied to the ESLCarousel element (except navigation related plugins).

Here is a list of available plugins: