Vue Guide

Basic Slider

The <Reel> component wraps the core slider controller. Use the #item slot to render each slide with virtualization — only visible slides are mounted.

ReelIndicator

Optional component that displays Instagram-style progress indicators showing the current position in the slider. When placed inside a <Reel>, it auto-connects to the parent's count and active values via Vue's provide/inject — no manual wiring needed.

Imperative API — Template Ref

The <Reel> component exposes a ReelExpose interface via template ref. Use ref() to store the reference and call imperative methods like next(), prev(), and goTo().

Horizontal Direction

Set direction="horizontal" for a left/right swipe slider. The indicator direction should match.

Auto-sizing

The size prop is optional. When omitted, <Reel> auto-measures its container via ResizeObserver and adapts to CSS-driven layout. The container must be sized by its parent (e.g. flex, grid, or explicit CSS dimensions).

Transitions

Pass a transition prop to customize the slide animation. ReelKit ships five tree-shakeable transitions: slideTransition (default), fadeTransition, flipTransition, cubeTransition, and zoomTransition.

Loop Mode

Enable infinite circular navigation with the loop prop. The slider wraps seamlessly from the last slide back to the first (and vice versa).

Event Callbacks

The <Reel> component emits several events for tracking slider state:

Navigation

Built-in navigation methods:

• Touch/Swipe: Drag to navigate with momentum and snap
• Keyboard: Arrow keys and Escape
• Mouse Wheel: Enable with :enable-wheel="true"
• Programmatic: Use a template ref to access next(), prev(), goTo()

#item Slot Pattern

Instead of React's render prop, Vue uses the #item scoped slot. This enables virtualization — only visible slides are mounted. The slot scope provides three properties:

Composables

@reelkit/vue provides composables for common overlay scenarios:

Key Points

• Composition API

  Import Reel, ReelIndicator, and composables directly into your <script setup> — no plugin registration required

• #item scoped slot

  The Vue equivalent of React's itemBuilder prop — enables virtualization with familiar template syntax

• Template ref

  Use ref<ReelExpose>() for imperative navigation — no event callbacks required

• @after-change

  Emits (index, rangeIndex) — track current index for UI updates

• provide/inject context

  ReelIndicator auto-connects to the parent Reel via Vue's provide/inject — no manual prop drilling

Performance Tips

• Keep slide templates lightweight

  The #item slot runs for each visible slide (typically 3 at a time). Avoid heavy computation or deeply nested structures inside it.

• Load data near the edge

  Use @after-change to detect when the user approaches the end and fetch the next batch before slides run out — enabling infinite scroll feeds.

• Use refs for imperative state

  Store the ReelExpose reference and current index in Vue ref()s for fine-grained reactivity without unnecessary re-renders.

• Disable wheel in scrollable pages

  Set :enable-wheel="false" when the slider is embedded in a scrollable layout to avoid capturing the page scroll.