README.md

flex-carousel

A carousel using flexbox.

Planned Features

• aria support
• initialize components automatically
• event hooks?
  • fc:init
  • fc:play
  • fc:pause
  • fc:slide
  • fc:slid
• support flex-direction: column?

Usage

data-flex-carousel

Used to mark an element as a carousel in a carousel group. The value should be the name of the carousel item. Having multiple carousels with the same name is supported.

Syntax: data-flex-carousel="<carousel-group-name>"

data-flex-carousel-control

Used to mark an element as a control for a given carousel group.

Syntax: data-flex-carousel-control="<carousel-group-name>:<event>[:<parameter>]"

data-flex-carousel-item optional

Used to configure an individual item of the carousel.

Syntax: data-flex-carousel-item="<property>: <value>[...; <property>: <value>]"

Available properties:

• speed: the time (in ms) the item will be visible

data-flex-carousel-indicator optional

Used to mark an element as an active indicator for a given item in a given carousel group. When the given item is active, this element will have the data-flex-carousel-indicator-active attribute added and (if supplied) will have the active-class added to the classList.

Syntax: data-flex-carousel-indicator="<carousel-group-name>:<item-index>[:<active-class>]"

JS Initialization

By default, all tags marked with a recognized attribute are initialized when flex-carousel loads. This can be prevented by stopping the fc:init event on the document. You can then create the components yourself.

document.addEventListener('fc:init', (e) => {
    e.stopImmediatePropagation();

    new FlexCarousel(document.getElementById('my-carousel'));

    new FlexCarouselControl(document.getElementById('next-button'));

    document.querySelectorAll('.my-indicator').forEach((el) => new FlexCarouselIndicator(el));
});

Examples

The data-* format is suggested, but not required. For instance data-flex-carousel and flex-carousel will work equally well. If both attributes are found on an element, the data-* version will be used.

<div class="carousel-wrapper">
    <div class="carousel" data-flex-carousel="carousel">
        <div data-flex-carousel-item="speed: 10000">...</div>
        <div data-flex-carousel-item="speed: 8000">...</div>
        ...
    </div>
    <ul>
        <li data-flex-carousel-control="carousel:slide:0" data-flex-carousel-indicator="carousel:0">...</li>
        <li data-flex-carousel-control="carousel:slide:1" data-flex-carousel-indicator="carousel:1">...</li>
        ...
    </ul>
    <button type="button" data-flex-carousel-control="carousel:slide:-1">Prev</button>
    <button type="button" data-flex-carousel-control="carousel:slide:+1">Next</button>
    <button type="button" data-flex-carousel-control="carousel:slide:play">Play</button>
    <button type="button" data-flex-carousel-control="carousel:slide:pause">Pause</button>
</div>

By default, the shortened attribute data-fc can also be used.

<div class="carousel-wrapper">
    <div class="carousel" data-fc="carousel">
        <div data-fc-item="speed: 10000">...</div>
        <div data-fc-item="speed: 8000">...</div>
        ...
    </div>
    <ul>
        <li data-fc-control="carousel:slide:0" data-fc-indicator="carousel:0">...</li>
        <li data-fc-control="carousel:slide:1" data-fc-indicator="carousel:1">...</li>
        ...
    </ul>
    <button type="button" data-fc-control="carousel:slide:-1">Prev</button>
    <button type="button" data-fc-control="carousel:slide:+1">Next</button>
    <button type="button" data-fc-control="carousel:slide:play">Play</button>
    <button type="button" data-fc-control="carousel:slide:pause">Pause</button>
</div>

The list of available attribute prefixes can be modified with the property FlexCarousel.defaults.prefixes. To register new prefixes, attach a handler to the fc:init event on the document.

// register the attribute prefix 'foo' to allow the use of '[data-]foo', '[data-]foo-control', etc.
document.addEventListener('fc:init', function oninit() {
    FlexCarousel.defaults.prefixes.push('foo');
});

Development

To build the project run:

npm run build

To watch for changes run:

npm run watch

To start serving the examples run:

npm run web

To watch for changes and start the local server run:

npm run dev

To build documentation run:

npm run documentation

API

DIRECTION

Enum for carousel direction.

FORWARD

The forward direction: forward.

REVERSE

The reverse direction: reverse.

FlexCarouselConfig

Type: Object

Properties

• initialIndex number The initial item index (default: 0).
• autoPlay boolean Whether to start playing the carousel after initialization (default: true).
• direction DIRECTION The direction the carousel slides (default: DIRECTION.FORWARD).
• speed number The speed (in ms) of the carousel (default: 5000).
• prefixes Array<string> A reference to the list of prefixes that can be used for components (default: ['flex-carousel', 'fc'])

FlexCarouselIndicatorConfig

Type: Object

Properties

• activeClass string The class to be applied to indicators when their item is active (default: '').

FlexCarousel

Class responsible for carousel functionality.

Parameters

• el
• config

constructor

Creates a FlexCarousel.

Parameters

• el Element The Element to use as a carousel.
• config FlexCarouselConfig? Configuration for the carousel.

slide

Moves the carousel to the given position.

Parameters

• direction (string | number) The zero based index of the target item, or the strings 'forward' (or '+1'), or 'backward' (or '-1').

play

Starts automatically moving the carousel.

pause

Stops automatically moving the carousel.

toggle

Toggles the play state of the carousel.

defaults

Gets the global default settings for carousels.

defaults

Sets the global default settings for carousels.

Parameters

• defaults FlexCarouselConfig The default global options.

FlexCarouselControl

Class responsible for carousel control functionality.

Parameters

• el

constructor

Creates a FlexCarouselControl.

Parameters

• el Element The Element to use as a carousel control.

onclick

The handler called when the control is clicked.

FlexCarouselIndicator

Class responsible for carousel indicator functionality.

Parameters

• el
• config

constructor

Creates a FlexCarouselIndicator.

Parameters

• el Element The Element to use as a carousel indicator.
• config FlexCarouselIndicatorConfig? Configuration for the carousel indicator.

onslid

The handler called when the carousel dispatches the fc:slid event.

Parameters

• e CustomEvent The CustomEvent representing fc:slid.
  • e.detail number The index of the current item.

defaults

Gets the global default settings for carousel indicators.

defaults

Sets the global default settings for carousel indicators.

Parameters

• defaults FlexCarouselIndicatorConfig The default global options.