demo

Get started

z-carousel is available on npm, published as @benavern/z-carousel.


npm

The component is available here on npm, you can install it via this command:

npm i @benavern/z-carousel

Then you can use it in your scripts like so in your js/ts module files: 

import '@benavern/z-carousel';

CDN

<script type="module" src="https://unpkg.com/@benavern/z-carousel"></script>

Have fun

For example you can use it to display a slider of images

<z-carousel>
  <img src="https://picsum.photos/960/540?random=1">

  <img src="https://picsum.photos/960/540?random=2">
</z-carousel>

Any HTML will work

<z-carousel>
  <p>
    Lorem ipsum dolor sit, amet consectetur adipisicing elit. Inventore vel recusandae quae accusamus, dolore facilis maxime laboriosam quod provident magni in voluptates unde ex. Eveniet ex a expedita numquam soluta?
  </p>

  <p>
    Earum voluptas eius modi consequatur debitis omnis excepturi enim dolorum aut eos. Illum consequatur, commodi, temporibus doloribus unde laboriosam quam adipisci cum, obcaecati incidunt animi dolore quo accusantium possimus voluptatem?
  </p>
</z-carousel>

Lorem ipsum dolor sit, amet consectetur adipisicing elit. Inventore vel recusandae quae accusamus, dolore facilis maxime laboriosam quod provident magni in voluptates unde ex. Eveniet ex a expedita numquam soluta?

Earum voluptas eius modi consequatur debitis omnis excepturi enim dolorum aut eos. Illum consequatur, commodi, temporibus doloribus unde laboriosam quam adipisci cum, obcaecati incidunt animi dolore quo accusantium possimus voluptatem?

Base

Here is the raw component, you can add anything inside. Each root element will be considered as a slide unless you use one of the defined slots.

To interact with the carousel on (non-touch) desktop, give focus to the component (tab through the document) and start using keyboard arrows.

You can also scroll horizontaly with your mouse if it can do it.

On mobile, you can swipe with your finger from page to page.

Drag

You can use the drag attribute to enable swiping on non-touch devices.

This should not do anything on touch devices as it already is touch friendly

You can add navigation buttons. When a navigation is possible, it can be clicked, otherwize, the button will be disabled.

By default, the navigation buttons are provided with html arrow entities &lsaquo; (‹) and &rsaquo; (›).

It is possible to customize the content of the navigation buttons by using the slot="nav-prev" and slot="nav-next" slots.

Before After 
<span slot="nav-prev">
  Before
</span>

<span slot="nav-next">
  After
</span>

Infinit

It is possible to cycle threw the carousel with the infinit attribute.

Current page

It is possible initialize the carousel on a given page with the current-page attribute

Multiple items per page

You can decide to display multiple slides per page.

Pagination

You can add a fraction counter for pagination, this will show the current page number over the total pages number

Gap

You can add a little bit of space betwin the slides by using the gap property.

Dots

You can show dots for every page, each dot has the page number as text in it.

The current one is not clickable and the others will slide the carousel to the corresponding page when clicked.

Disabled

You can disable all interaction on the element with the disabled attribute.

You can still use the component methods programaticaly.

Events

A change event fires when the component is about to change page.

This event is a CustomEvent, you have acces to current and next page numbers in the event detail object and it is cancelable. 

document.querySelector('z-carousel#event-demo')?.addEventListener('change', (event) => {
    console.log(event);

    if ((event as CustomEvent).detail.next === 5) {
        event.preventDefault();
        alert('this action has been canceled!');
    }
});

Full demo

Here is an example of what you could achieve with this component and a little bit of css styling: See CSS

You can style some ::part() elements of the component

::part(content)
::part(nav-btn /* nav-btn--prev nav-btn--next nav-btn--disabled */)
::part(pagination)
::part(dots)
::part(dots-item /* dots-item--active */)