Carousel

It is highly recommended to read the entire page first before using the component yourself!

The carousel is a component for displaying different content, which are displayed horizontally next to each other and in which you can navigate horizontally.

The carousel component is highly adaptable to your own needs, from self-defined controls, cycling movements behavior, define how many slides should be displayed at the same time and much more…

Basic Variant

In the absolute basic variant, the individual contents is displayed in the same width as the parent element and an automatic circle slides always to the next content.

The general structure consists of the block .carousel and the two elements .carousel__slide-container and .carousel__slide. Your individual content must be inserted within the .carousel__slide.

.carousel
  .carousel__slide-container
    .carousel__slide
      ...
    .carousel__slide
      ...
    .carousel__slide
      ...

The carousel is as high as your highest content. If you want all contents to be at the same height, you should give your content a container with the global modifier class .height-100-%.

The Cycling Movements, which is described in more detail below, has a default time delay of 5 seconds and stops when the browser tab is inactive.

In the .carousel__slide-container we use normal browser scrolling with the CSS scroll-snap-type property. This allows the user to switch between slide per swipe gestures on touch devices.

The following example shows such a basic variant:

Controls

There are three types of control elements

• A left center oriented control to go to the previous slide. This is referred as PREV.
• A center-right oriented control to move to the next slide. This is referred as NEXT.
• A list of navigation items, oriented bottom center, with one item per slide. The navigation is referred as NAV and the individual elements as NAVITEM.

With the help of the HTML template tags, you define what these elements should look like, and the scripting adds them at the appropriate places and in the appropriate number. In addition, settings can be made on the controls with additional data attributes.

To display a control, you must add the .carousel__controls to the block. The following templates can placed in this element:

• <template data-sg-carousel-template="prev"><!-- YOUR PREV CONTROL --></template>
• <template data-sg-carousel-template="next"><!-- YOUR NEXT CONTROL --></template>
• <template data-sg-carousel-template="nav-item"><!-- YOUR NAVITEM CONTROL --></template>

.carousel
  .carousel__slide-container
    .carousel__slide
      ...
    .carousel__slide
      ...
    .carousel__slide
      ...
  .carousel__controls
    <template data-sg-carousel-template="prev">...</template>
    <template data-sg-carousel-template="next">...</template>
    <template data-sg-carousel-template="nav-item">...</template>

The following shows an example of using the template tags to add your own controls:

Control Settings

With a series of data attributes, which must be added directly to the HTML of the self-defined control elements, the controls can receive additional information.

The data attribute [data-sg-carousel-template-active-class] can be added to an HTML tag of a NAVITEM. The value of the attribute is added to the tag as a class if the slide associated with the NAVITEM is currently being displayed. It will be removed when the slide is no longer displayed. this allows you to create an active / inactive toggler.

Example:

<template data-sg-carousel-template="nav-item">
  <span
    class="icon icon--dot border-radius-circle pointer padding-0.50 border-thin"
    data-sg-carousel-template-active-class="border-color-blue"
  ></span>
</template>

The data attribute [data-sg-carousel-template-text] can be added to an HTML tag of a PREV, NEXT or NAVITEM. The value of the attribute replaces the visible text of the tag. You can pass certain template strings as value, which are replaced accordingly localized:

• {PREV} Replace with the localized word “Previous”.
• {NEXT} Replace with the localized word “Next”.
• {GOTO} Replace with the localized word “Goto”.
• {SLIDE} Replace with the number of the related slide. Only works on a NAVITEM.

You can also add the data attribute [data-sg-carousel-template-tooltip] to PREV, NEXT and NAVITEM. It work in the same as the data-sg-carousel-template-text, except that a tooltip is attached to the element instead.

Example:

<template data-sg-carousel-template="prev">
  <span data-sg-carousel-template-text="{PREV}"></span>
</template>
<template data-sg-carousel-template="next">
  <span data-sg-carousel-template-text="{NEXT}"></span>
</template>
<template data-sg-carousel-template="nav-item">
  <span
    class="icon icon--dot border-radius-circle pointer padding-0.50 border-thin"
    data-sg-carousel-template-tooltip="{GOTO} {SLIDE}"
  ></span>
</template>

The following shows an example of using the data attribute to customize your own controls:

Modifier

In the following subchapters the different classes modifier are described.

Number of Slides

You can change the number of slides displayed by adding the following modifiers to the block.

The values are:

• NUMBER 1, 2, 3, 4, 5
• SCREEN_SIZE lg, md, sm, xs

The structure of the modifier classes are:

• .carousel--{NUMBER}-slides
• .carousel--{NUMBER}-slides-{SCREEN_SIZE}

The following shows an example of using different number of slides:

Inner Navigation

With the help of the .carousel--inner-nav modifier, the NAV is moved to the inner area of the carousel. Accordingly, the NAVITEMS should also be given another suitable style.

Movements

Normally the slides move in a circular motion. I.e. when you have arrived at the last slide and navigate to the next one, the carousel jumps back to the first slide, and vice versa. This circular movement can be prevented by using the class modifier .carousel--prevent-rotation.

If the circular movement is prevented, the control elements PREV/NEXT are deactivated as soon as you arrive to the first/last slide with the global modifier disable. This deactivation can be prevented by using class .carousel--prevent-disable-controls.

By default, the component starts automatically with the movement to the next slide and continues this automation every 5 seconds. If the browser tab is inactive, this automatic is paused until you return to the browser tab. For this function we use the Page Visibility API library. You can prevent this behavior with the class modifier .carousel--prevent-browser-tab-visibility-listing.

If the user uses a control, the automatic rotation is stopped completely.

The standard automatic rotation to the next slide can be prevented completely using the class modifier .carousel--prevent-auto-rotation.

In the following example we disable the automatic rotation and stop the circular movement.

Change timer

You can change the stop timer for automatic rotation with the data attribute [data-sg-carousel-cycling-timer]. It must be a number an represent milliseconds.

Example to slowdown the cycling for move only every 10 seconds.

<div class="carousel" data-sg-carousel-cycling-timer="10000">
  <div class="carousel__slide-container">
    <div class="carousel__slide">...</div>
    <div class="carousel__slide">...</div>
  </div>
</div>

Goto mostly hidden slide

The user can switch to a slide, that is partial shown by clicking on them. This works especially with the Show Next Slides modifier. It is part of the movements and also “hidden” control. Like all other controls, the automatic rotation will stopped when using this control. The behavior can be prevented with the modifier class .carousel--prevent-slide-click-movement.

Show Scrollbar

As described above, we use normal browser scrolling inside the slide container. The scrollbar is hidden by default. This can be displayed using the class modifier .carousel--show-scrollbar.

Show Next Slides

In the standard case, if you currently at the first/last slide, or you only show one slide, the other slides are not visible. Only if you display more than one slide at the same time with the Number of Slides modifier, you can partially see the other slides. In order to always be able to see the other slides at the edges, there is the extra modifier .carousel--show-next-slide.

Note This class modifier works especially fine with the Goto mostly hidden slide control.

Show Shades

With the help of the .carousel--show-shades class modifier, shades can be displayed on the sides, which indicate that there are more slides.

Observer

The carousel use the Observer Pattern. The carousel is a subject and notify all observers, if an slide is changed to current state.

Simplified excerpt from carousel.ts:

type Carousel = TComponent;
type Slide = HTMLElement;
type Elements = {
  slideContainer: HTMLElement;
  slideList: Slide[];
  currentSlide?: Slide;
  controls?: HTMLElement;
  prev?: HTMLElement;
  next?: HTMLElement;
  nav?: HTMLElement;
  navItems: NavItem[];
  templates: {
    prev?: HTMLTemplateElement;
    next?: HTMLTemplateElement;
    navItem?: HTMLTemplateElement;
  }
}
type CarouselData = { carousel: Carousel, slide: Slide, slideIndex: number }

class CarouselHandler extends Subject<CarouselData> {
  public goto(carousel: Carousel, gotoIndex: GotoIndex): void {
    /* ... */

    this.setCurrentSlide(carousel, slide);
  }

  public getElements(carousel: Carousel): Elements { /* ... */ }

  public getSlideIndex(slide: Slide): number { /* ... */ }

  private setCurrentSlide(carousel: Carousel, slide: Slide): void {
    /* ... */

    this.notifyObserver(carousel);
  }

  protected notifyObserver(carousel: Carousel): void {
    const carouselData = this.toData(carousel) as CarouselData;
    super.notify(carouselData);
  }
}

You can listen to the notification by adding into the carousel as an observer.

import { styleGuide, Observer } from '@finanzen-net/style-guide';

/**
 * This is what your code should look like
 */
class YourClass extends Observer {
   update({carousel, slide}) {
     console('In the carousel', carousel, 'the slide', slide, 'was activated.');
   }
}

const yourClass = new YourClass();
styleGuide.carouselHandler.addObserver(yourClass);

Examples

In this section we show a few examples of how to use the carousel.

Banner Example

In this example, we’re going to display a full wide banner that combines advertising, data tables and article.

We use small flat buttons for the NAVITEM elements so that they also have a hover effect. In addition, we give the NAVITEM elements an individual tool tip.

By alternating light and dark slides, we make the carousel more visually appealing : )

Since we only use class colors, the style also changes depending on the used theme.

Article Example

In this example we show how the carousel can be used in combination with other elements. Depending on the screen size, we show the carousel to the right or below the primary article display. We also change the number of slides shown depending on the screen size.

News Leading Example

This example shows, how to connect multiple carousels to one control.