Plugins

Plugins extend the slider with UI features — navigation arrows, pagination, autoplay, accessibility, keyboard control, and more. They are installed via the plugins option and follow a simple install / destroy lifecycle. Each plugin is a separate named export so you import only what you use — unused plugins are tree-shaken out and add zero bytes to your final bundle.

Installation

npm install @andresclua/sliderkit-plugins
# or
pnpm add @andresclua/sliderkit-plugins

Usage

// Only import what you use — unused plugins are tree-shaken out of your bundle
import { Slider } from '@andresclua/sliderkit'
import { arrows, pagination } from '@andresclua/sliderkit-plugins'

new Slider('#el', {
  plugins: [
    arrows(),
    pagination({ type: 'dots', clickable: true }),
  ],
})

Available plugins

Plugin	Import	Description
arrows	`arrows(opts?)`	Previous / next navigation buttons.
pagination	`pagination(opts?)`	Dots, fraction, or progress bar pagination.
autoplay	`autoplay(opts?)`	Auto-advance on a fixed interval. Pauses on hover, focus, touch, and drag.
a11y	`a11y(opts?)`	WAI-ARIA carousel pattern — roles, roledescriptions, and slide labels.
mouseWheel	`mouseWheel(opts?)`	Navigate with the mouse wheel or trackpad. Cooldown prevents mid-transition skips.
keyboard	`keyboard(opts?)`	← → arrow keys navigate when the slider is focused. ↑ ↓ for vertical sliders.
progress	`progress(opts?)`	Progress bar that fills as you advance through the slides.
thumbs	`thumbs(opts)`	Thumbnail strip synced to the slider. Click a thumb to jump to that slide.
hooks	`hooks(callbacks)`	Lifecycle callbacks (onInit, beforeChange, afterChange, onDragStart, onDragEnd, onResize, beforeDestroy) for custom animations with GSAP or similar.

Plugins and responsive breakpoints

plugins cannot be set inside the responsive map — it only supports layout options like items and gutter. If you need a plugin active only above a certain breakpoint, build the array conditionally before creating the slider:

const plugins = [arrows()]

if (window.innerWidth >= 960) {
  plugins.push(progress({ container: '#my-progress' }))
}

new Slider('#el', { plugins })

If you also need plugins to swap on resize, destroy and recreate the slider when the breakpoint zone changes:

function getZone() {
  if (window.innerWidth < 640)  return 'sm'
  if (window.innerWidth < 960)  return 'md'
  return 'lg'
}

function buildPlugins(zone) {
  const p = [arrows()]
  if (zone === 'sm') p.push(pagination({ type: 'dots' }))
  if (zone === 'lg') p.push(progress({ container: '#progress' }))
  return p
}

let zone = getZone()
let slider = new Slider('#el', { plugins: buildPlugins(zone) })

let t
window.addEventListener('resize', () => {
  clearTimeout(t)
  t = setTimeout(() => {
    const next = getZone()
    if (next === zone) return
    zone = next
    slider.destroy()
    slider = new Slider('#el', { plugins: buildPlugins(zone) })
  }, 150)
})

Writing your own plugin

A plugin is a plain object with name, install, and destroy. Wrap it in a factory function so options are closed over.

import type { SliderPlugin, SliderInstance } from '@andresclua/sliderkit'

function myPlugin(opts = {}): SliderPlugin {
  let slider: SliderInstance

  return {
    name: 'my-plugin',

    install(s: SliderInstance) {
      slider = s
      slider.on('indexChanged', (info) => { console.log('slide →', info.displayIndex) })
    },

    destroy() {
      // remove DOM nodes, event listeners, etc.
    },
  }
}

The install method receives the full SliderInstance. Use slider.on / slider.off to react to events, and slider.outerWrapper to inject UI elements.