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

ESLCarouselSlideTarget type

The ESLCarouselSlideTarget is a string that defines the target slide for the carousel navigation.

The following nav strings (commands) are available:

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 utilizes JS Animation API to animate the slides. The only way to customize the transition timing is to use the step-duration attribute on the esl-carousel element.
  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).

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).

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: