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()

URL State

useOverlayUrlState builds a URL-state controller for an overlay and returns it whole, then you hand it to a <LightboxUrlOverlay> as its :controller prop. The address bar owns the open state, so a bound overlay opens itself and a link is the usual open action. The first write of an absent parameter pushes one history entry and every write after replaces it, so paging never buries the back button. Keep the controller to read value/position and to close programmatically with set(null), the same low-level write the overlay uses internally on slide change.

The options object takes param, codec, and locator (all three required), plus an optional adapter. The codec and locator are a matched pair sharing the same Id, so for a plain ?photo=3 gallery spread ...urlIndexKey(() => props.images.length), which returns both halves at once. urlIndexKey maps the parameter to a slide index and bounds it against the live count the getter returns, so a stale or out-of-range ?photo=99 is rejected and heals itself out of the URL instead of opening a slide that was never named. Pass a getter, not a number: a Vue setup runs once, so a captured length would go stale as a paginated feed grows. It wraps createIndexLocator (the locator half) and pairs it with indexCodec. A paginated feed or an identity-keyed gallery supplies its own matched codec + locator instead. The full options table lives on the Vue API reference.

#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.