Fylgja Snap Slider

A CSS-powered slider/carousel, enhanced with JavaScript for improved functionality and accessibility.

The Snap Slider is available as a Custom Element (the primary and recommended way) or as an AlpineJS component.

Custom Element Live Demo: https://fylgja-snap-slider.netlify.app/
AlpineJS Live Demo: https://fylgja-snap-slider.netlify.app/alpinejs

Installation

The Snap Slider can be integrated into your project via NPM or by using a CDN.

NPM Installation

Install the package from NPM:

npm install @fylgja/snap-slider

CDN Integration

Alternatively, you can include the script directly in your HTML using a <script> tag.

For the Custom Element:

<script defer src="https://unpkg.com/@fylgja/snap-slider/dist/custom-element/cdn.min.js"></script>

For the AlpineJS version:

<script defer src="https://unpkg.com/@fylgja/snap-slider/dist/alpine/cdn.min.js"></script>

Usage

The Snap Slider can be used as a Custom Element or as an AlpineJS component.

Custom Element (Recommended)

Import the custom element into your project:

import '@fylgja/snap-slider/custom-element';

Then, use the <snap-slider> element in your HTML. A [data-track] child element is required to contain the slides.

<snap-slider>
    <div data-track>
        <!-- Your slides go here -->
    </div>
</snap-slider>

AlpineJS Component

To use the AlpineJS version, import the component and register it with Alpine:

import Alpine from 'alpinejs';
import snapSlider from '@fylgja/snap-slider/alpine';

window.Alpine = Alpine;

Alpine.plugin(snapSlider);
Alpine.start();

Then, apply the x-snap-slider directive to your slider element.

<div x-data x-snap-slider>
    <div data-track>
        <!-- Your slides go here -->
    </div>
</div>

Configuration

The snap-slider supports the following data attributes for configuration:

Data Attribute	Description	Default
`data-track`	Required. Identifies the container for the slider’s slides.
`data-next`	Designates a button to navigate to the next slide.
`data-prev`	Designates a button to navigate to the previous slide.
`data-pager`	Designates the container for pagination markers.
`data-auto-pager`	Automatically generates pagination markers.	`false`
`data-group-pager`	Groups pager markers based on the number of visible slides.	`false`
`data-slide-label-sepparator`	Customizes the separator in the `aria-label` for slides (e.g., “1 of 12”).	`of`
`data-pager-class`	Sets custom classes for the pager container.	`pager`
`data-marker-class`	Sets custom classes for the pager markers.	`pager-item`

AlpineJS Configuration

For the AlpineJS version, boolean options like auto-pager and group-pager are passed as modifiers to the x-snap-slider directive:

<div x-data x-snap-slider.auto-pager.group-pager>
    ...
</div>

Other data attributes can be applied directly to the element as usual.

You can add a pager to your slider in two ways:

The easiest way to add a pager is by using the data-auto-pager attribute (or x-snap-slider.auto-pager for AlpineJS). This will automatically generate a pager for you.

By default, the pager is inserted after the [data-track] element. You can customize its location by adding an empty [data-pager] container anywhere inside the slider element.

For more control, you can create a custom pager. Each slide must have a unique ID, and each pager marker must link to a slide’s ID using href="#slide-id" or data-target-id="slide-id".

When multiple slides are visible at once, you can use the data-group-pager attribute (or x-snap-slider.group-pager for AlpineJS) to group the pager markers. This will only show one marker for each visible group of slides.

JavaScript API

You can interact with the slider programmatically using the following methods and events.

Methods

First, get the SnapSlider instance:

For the Custom Element:

const snapSliderElement = document.querySelector('snap-slider');
const snapSliderInstance = snapSliderElement.slider;

For the AlpineJS component:

const sliderEl = document.querySelector('[x-snap-slider]');
const snapSliderInstance = sliderEl.snapSlider;

Method	Description
`init()`	Initializes the slider. This is called automatically.
`destroy()`	Removes all event listeners and observers.
`refreshSlides()`	Re-initializes the slider, useful when slides are added or removed dynamically.

Events

The slider dispatches a slideChange event on the slider element whenever the in-view slides change.

const sliderEl = document.querySelector('snap-slider'); // Or '[x-snap-slider]'
sliderEl.addEventListener('slideChange', (event) => {
    console.log(event.detail);
});

The event.detail object contains the following properties:

Property	Description
`inViewSlides`	An array of the slides currently in view.
`totalInViewSlides`	The total number of slides in view.
`firstInViewSlide`	The first slide in view.
`lastInViewSlide`	The last slide in view.
`isAtStart`	A boolean indicating if the slider is at the beginning.
`isAtEnd`	A boolean indicating if the slider is at the end.
`hasNoOverflow`	A boolean indicating if all slides are visible at once.