Table of Contents & Menu
On this page
Navigation

The Alpine.js x-snap-slider plugin

Available since Hyvä 1.4

The Hyvä Snap Slider is an Alpine.js plugin for creating accessible, customizable CSS-driven sliders.

It enhances existing CSS sliders with essential interactive features.

Usage

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

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

Slider interactivity is managed by CSS applied to elements within the [data-track] container.

Important: The plugin provides JavaScript logic, but slider visuals depend entirely on your CSS.

It prioritizes accessibility by automatically managing the inert attribute for off-screen slides and adding ARIA labels.

Enhance the slider with navigation buttons (next/previous) and pagination markers using specific data- attributes (see "Configuration Options").

Core Principle: The Hyvä Snap Slider uses progressive enhancement, relying on CSS for styling and JavaScript for interactivity and accessibility.

Modifiers

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

.auto-pager

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

To control placement, include an empty [data-pager] container within the snap-slider element; the pager will be inserted there.

<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 data-pager to prevent layout shifts.

Style the auto-generated pager using default CSS classes .pager and .marker. For custom styling or utility libraries, apply your own classes using data-pager-classes and data-marker-classes attributes on the x-snap-slider element.

.group-pager

The .group-pager modifier automatically groups pagination dots when multiple slides are visible.

Configuration Options

The snap-slider plugin uses these 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 options use HTML data- attributes (e.g., [data-track]).

Custom Pager Implementation

For custom pagers, each slide within [data-track] needs a unique id. These IDs link pager markers to slides, using either:

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

Style custom pager markers entirely with CSS.

How to, Demo and Examples

For details on building CSS sliders with Snap Slider, see the UI docs: How to build CSS sliders.

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

Autoplay

The Snap Slider follows CSS scroll-snap and does not support autoplay. This is an intentional design decision.

Why No Autoplay?

From an accessibility (A11Y) standpoint, auto-advancing sliders pose several challenges:

  • Users with motor impairments may need more time to interact with slider controls
  • Screen reader users can lose their place when content changes unexpectedly
  • Users with cognitive disabilities may find auto-advancing content disorienting
  • Auto-advancing can interfere with users who are reading or processing the content

For these reasons, the Snap Slider prioritizes user control over automatic transitions.

Alternatives for Autoplay Requirements

If autoplay is genuinely required, Hyvä offers these alternatives via the Hyvä UI library:

  1. Marquee Slider (Hyvä UI) - Recommended for non-interactive, decorative content where continuous motion aligns with UX and A11Y (e.g., scrolling brand logos, testimonials).

  2. SplideJS (Hyvä UI Plugins) - A traditional JavaScript-based slider that supports autoplay. Use only when autoplay is a firm requirement, as it trades accessibility benefits for features.

Recommendation

Before implementing autoplay, consider if your content truly benefits. User-controlled navigation generally provides a better experience.