Skip to content

The Alpine.js x-snap-slider plugin

Info

This plugin is currently available with Hyvä UI and Hyvä CMS. There are plans to add it to the theme. For now, you need to implement it yourself, using the instructions in the Hyvä UI Plugin.

The Hyvä Snap Slider is an AlpineJS plugin that empowers you to create accessible and highly customizable CSS-driven sliders.

It enhances your existing CSS slider implementations by adding essential interactive features.

Usage

To initialize a snap-slider, your HTML structure needs a container element with the x-data directive and a direct child element with the [data-track] attribute.

<section x-data x-snap-slider>
    <div data-track>
        <!-- Slides here go here -->
    </div>
</section>

The interactive behavior of the slider is then managed by the CSS styles you apply to the elements within the [data-track] container.

Important: While the plugin provides the JavaScript logic, the visual presentation of the slider is entirely dependent on your CSS styling.

This component prioritizes accessibility by automatically managing the inert attribute for off-screen slides and adding appropriate ARIA labels, ensuring a better experience for all users.

You can further enhance the slider with navigation buttons (next/previous) and pagination markers by adding elements with specific data- attributes (explained in the "Configuration Options" section).

Core Principle: The Hyvä Snap Slider follows a progressive enhancement approach. It relies on CSS for the fundamental styling and uses JavaScript to add interactivity and accessibility features.

Modifiers

The x-snap-slider directive accepts modifiers to customize its default behavior.

.auto-pager

The .auto-pager modifier automatically generates a set of pagination markers (dots) after the [data-track] element.

To control the placement of the auto-generated pager, include an empty [data-pager] container within the snap-slider element. The pager will be inserted into this container.

<section x-data x-snap-slider.auto-pager>
    <div data-track>
        <!-- Slides here go here -->
    </div>
    <div data-pager></div>
</section>

Consider setting a min-height on the data-pager to prevent layout shifts as the pager is added.

You can style the auto-generated pager using the default CSS classes .pager and .marker. Alternatively, for integration with CSS utility libraries or custom styling, you can apply your own classes using the data-pager-classes and data-marker-classes attributes on the x-snap-slider element.

.group-pager

The .group-pager modifier automatically groups the pagination dots if more slides are visible.

Configuration Options

The snap-slider plugin utilizes the following data- attributes for configuration:

Data Attribute Description
data-track Identifies the HTML element that contains the individual slides of the slider.
data-next Designates the HTML element (e.g., a button) that triggers navigation to the next slide.
data-prev Designates the HTML element (e.g., a button) that triggers navigation to the previous slide.
data-pager Specifies the HTML element that will serve as the container for custom pagination markers.
data-slide-label-sepparator Allows you to customize the separator used when generating accessible labels for slides (e.g., "Slide 1 of *").

All configuration options are implemented using HTML data- attributes (e.g., [data-track]).

Custom Pager Implementation

When implementing a custom pager, each slide within the [data-track] element must have a unique id attribute. These IDs are then used to link the pager markers to their corresponding slides. This can be achieved using either:

  • Anchor links (<a> tags): Set the href attribute of the link to the slide's ID prefixed with a hash (#).
  • Buttons: Use <button> elements with the [data-target-id] attribute set to the corresponding slide's ID.

Styling the appearance of your custom pager markers is entirely up to your CSS implementation.

How to, Demo and Examples

For more information on how to build CSS sliders with the Snap Slider, check out the UI docs: How to build CSS sliders.

Watch the video introduction to the Snap Slider for a visual demonstration.