@mihnsen/vue-slick

A Vue 3 (Composition API + TypeScript) port of the Slick carousel, aiming for full parity with the react-slick settings API. Same DOM structure and CSS class names as the original, so slick's stylesheets — and most slick-based custom CSS — keep working.

Features

• All ~40 react-slick settings, reactive at runtime: infinite loop, autoplay, fade, centerMode, vertical, RTL, variableWidth, adaptiveHeight, rows/slidesPerRow grid, responsive breakpoints (with 'unslick'), lazy loading, asNavFor synced carousels, and more
• Touch & mouse drag with slick's swipe thresholds, edge friction, and swipeToSlide
• Accessible: arrow-key navigation, aria-hidden management, dots as a tablist
• SSR-safe (Nuxt 3): full markup server-rendered with no hydration mismatch
• Zero runtime dependencies besides @vueuse/core; vue is a peer dependency
• Ships typed: full TypeScript definitions for settings, events, and the exposed API

Install

npm i @mihnsen/vue-slick

vue (^3.4) is a peer dependency.

CSS

Import the functional stylesheet (layout: list/track/slide positioning, vertical mode, fade, pre-init state) and, optionally, the theme stylesheet (default arrow/dot styling — SVG data-URI icons, no font files):

import '@mihnsen/vue-slick/slick.css'
import '@mihnsen/vue-slick/slick-theme.css'

Both are plain CSS; no preprocessor required.

Usage

Slot + individual props

<script setup>
import { SlickCarousel } from '@mihnsen/vue-slick'
import '@mihnsen/vue-slick/slick.css'
import '@mihnsen/vue-slick/slick-theme.css'
</script>

<template>
  <SlickCarousel :dots="true" :infinite="true" :slides-to-show="3" :slides-to-scroll="1">
    <div v-for="i in 6" :key="i">Slide {{ i }}</div>
  </SlickCarousel>
</template>

settings object

<script setup>
import { SlickCarousel } from '@mihnsen/vue-slick'
import '@mihnsen/vue-slick/slick.css'
import '@mihnsen/vue-slick/slick-theme.css'

const settings = {
  dots: true,
  infinite: true,
  slidesToShow: 3,
  slidesToScroll: 1,
  responsive: [
    { breakpoint: 768, settings: { slidesToShow: 1 } },
  ],
}
</script>

<template>
  <SlickCarousel :settings="settings">
    <div v-for="i in 6" :key="i">Slide {{ i }}</div>
  </SlickCarousel>
</template>

Settings can be passed as the settings object prop, as individual typed props, or both — precedence is defaults → settings object → individual props → the currently matched responsive breakpoint. A responsive entry whose settings is the string 'unslick' renders the slides as a plain, unstyled list.

Two additional props sit outside Settings: asNavFor — a template ref to another mounted SlickCarousel instance to synchronize navigation with — and currentSlide (used with v-model:currentSlide) for controlled binding of the active slide index.

Settings

| Name | Type | Default | Description | |---|---|---|---| | accessibility | boolean | true | Enables arrow-key navigation on the slider, aria-hidden on inactive/cloned slides, and role="tablist"/aria-selected on dots. | | adaptiveHeight | boolean | false | Resizes .slick-list to match the height of the current slide. | | arrows | boolean | true | Shows prev/next arrows (hidden automatically once slideCount <= slidesToShow). | | autoplay | boolean | false | Automatically advances slides on an interval. | | autoplaySpeed | number | 3000 | Milliseconds between auto-advances. | | centerMode | boolean | false | Centers the active slide with partial neighbor slides visible on both sides. | | centerPadding | string | '50px' | CSS length reserved on each side of the list in centerMode. | | cssEase | string | 'ease' | CSS transition-timing-function used for the track's transform transition. | | dots | boolean | false | Shows pagination dots below the slider (adds slick-dotted to the root element). | | dotsClass | string | 'slick-dots' | Class name applied to the dots <ul>. | | draggable | boolean | true | Enables mouse-drag dragging in addition to touch. | | easing | string | 'linear' | Accepted for react-slick API compatibility only — has no effect. See Limitations. | | edgeFriction | number | 0.35 | Resistance multiplier applied to drag movement past the first/last slide in finite mode. | | fade | boolean | false | Crossfades slides in place instead of sliding the track. | | focusOnSelect | boolean | false | Clicking a partially visible slide navigates to it. | | infinite | boolean | true | Wraps around at the ends using cloned slides. | | initialSlide | number | 0 | Index of the slide shown on mount. | | lazyLoad | 'ondemand' \| 'progressive' \| null | null | Enables data-lazy image loading — 'ondemand' promotes images as their slide becomes active, 'progressive' loads all of them in the background after mount. | | mobileFirst | boolean | false | When true, responsive breakpoints match viewport widths >= the breakpoint instead of <=. | | pauseOnDotsHover | boolean | false | Pauses autoplay while hovering the dots. | | pauseOnFocus | boolean | true | Pauses autoplay while the slider has focus. | | pauseOnHover | boolean | true | Pauses autoplay while hovering the slider. | | responsive | { breakpoint: number, settings: Partial<Settings> \| 'unslick' }[] \| null | null | Breakpoint-specific setting overrides; 'unslick' renders a plain unstyled list at that breakpoint. | | respondTo | 'window' \| 'slider' \| 'min' | 'window' | Which width drives responsive breakpoint matching — the window, the slider container, or the smaller of the two. | | rows | number | 1 | Number of rows per slide group (grid mode); combine with slidesPerRow. | | rtl | boolean | false | Right-to-left layout; also flips which arrow key navigates forward/back. | | slidesPerRow | number | 1 | Number of slides per row when rows > 1. | | slidesToShow | number | 1 | Number of slides visible at once. | | slidesToScroll | number | 1 | Number of slides advanced per navigation. | | speed | number | 500 | Transition duration in milliseconds. | | swipe | boolean | true | Enables touch/pointer swipe navigation. | | swipeToSlide | boolean | false | Lets a drag land on any slide (nearest-slide snap) rather than always moving by slidesToScroll. | | touchMove | boolean | true | Gates the whole drag/swipe layer: false disables pointer dragging entirely (not just the visual "follow the finger" motion). Splitting that from swipe for full react-slick parity is a deferred fast-follow. | | touchThreshold | number | 5 | Divisor of the list width used to compute the drag distance required to trigger navigation. | | useCSS | boolean | true | Enables the CSS transition on the track/slide; false makes changes apply instantly. | | useTransform | boolean | true | Positions the track with transform: translate3d; false uses left/top instead (still CSS-transitioned). | | variableWidth | boolean | false | Slides size to their own content width instead of an even split of the list. | | vertical | boolean | false | Stacks and navigates slides vertically instead of horizontally. | | verticalSwiping | boolean | false | Enables vertical-axis dragging when vertical is true. | | waitForAnimate | boolean | true | Ignores new navigation requests while a transition is already in progress. |

Events

| Event | Payload | Fires when | |---|---|---| | init | — | The carousel has mounted. | | re-init | — | The matched responsive breakpoint entry changes. | | before-change | (from: number, to: number) | Just before the current slide changes. | | after-change | (current: number) | After a slide change completes. | | edge | (direction: 'left' \| 'right') | Navigation is attempted past the first/last slide in finite mode. | | swipe | (direction: string) | A drag/swipe gesture completes. | | lazy-load | (indexes: number[]) | data-lazy images finish loading for the given slide indexes. | | lazy-load-error | (index: number) | A data-lazy image fails to load. | | update:currentSlide | (index: number) | The active slide index changes — pair with v-model:currentSlide. |

Exposed methods

Access via a template ref on <SlickCarousel ref="slick">:

| Method | Description | |---|---| | next() | Advance by slidesToScroll. | | prev() | Go back by slidesToScroll. | | goTo(index: number, dontAnimate?: boolean) | Jump to a specific slide index. | | play() | (Re)start autoplay. | | pause() | Stop autoplay. | | currentSlide | Read-only current slide index. |

goToUnsync(index) is also exposed; it exists to support asNavFor synchronization (it navigates without propagating back to a linked carousel, preventing ping-pong) and is not intended for direct use.

Slots

| Slot | Props | Purpose | |---|---|---| | default | — | Slide content — one child per slide (v-for works). | | prev-arrow | { disabled, onClick } | Replace the prev arrow's markup. | | next-arrow | { disabled, onClick } | Replace the next arrow's markup. | | dots | { dots: { count, current } } | Replace the whole dots list (equivalent to react-slick's appendDots). | | custom-paging | { index } | Replace an individual dot's content (equivalent to customPaging(i)). |

Limitations

• easing (jQuery-animation easing name in the original slick/react-slick) is accepted for API compatibility but is a documented no-op — this port drives transitions with native CSS transitions, and cssEase is the supported control for the timing curve.
• useCSS: false and useTransform: false are honored (see the settings table above) but are legacy escape hatches carried over from react-slick, not the recommended path.

SSR / Nuxt 3

SlickCarousel is SSR-safe and works out of the box with Nuxt 3: the full slide markup — including infinite-mode clones and arrows/dots — renders deterministically on the server using slick's own percentage-based sizing trick (track width = slideCount * 100 / slidesToShow%, each slide = 100 / totalPositions% of the track), which needs no layout measurement. All real measurement, event listeners, and VueUse browser utilities activate on the client in onMounted, so there is no window/document access during server rendering and no hydration mismatch. The slick-initialized class is added client-side only, once mounted.

Development

npm install
npm run dev        # playground: pages for basic, drag, layout modes, autoplay, synced nav
npm test           # vitest (jsdom + node SSR suite)
npm run typecheck  # vue-tsc
npm run build      # library build to dist/ (ES + UMD + d.ts + css)

License

MIT