Vue Reel Player

Features

Installation

Import the stylesheet once in your app entry (or any component):

Quick Start

Render a grid of thumbnails and open the overlay at the clicked index. Binding v-model:is-open means the parent ref stays in sync when the user closes the player via button, gesture, or Escape.

API Reference

Props

Events

v-model:is-open

Use v-model:is-open to drive the overlay with a single binding. The legacy :is-open + @close pattern still works if you need the explicit event.

Scoped Slots

Eight scoped slots let you replace any part of the player UI. Each receives a strongly-typed scope object. Slots you don't pass fall back to the defaults.

Custom Timeline

Replace the built-in playback bar with your own scrub UI via the #timeline slot. The slot fires only when the overlay's gating rules would render the default bar (same timeline mode + timelineMinDurationSeconds), so you don't re-implement it. Reuse the .rk-reel-timeline class on your root to inherit flush-bottom positioning, safe-area padding, and touch-device clearance.

Custom Content Types

ReelPlayerOverlay is generic over your content item shape. Extend BaseContentItem to use any data model, and import the matching slot-scope type to keep slot bindings strongly typed:

The same pattern works for every other slot. Import the matching scope type (SlideSlotScope, ControlsSlotScope, NavigationSlotScope, NestedSlideSlotScope, LoadingSlotScope) and annotate the destructure.

Types

ContentItem

TimelineBarProps

TimelineSlotScope<T>

MediaItem

Sub-Components

Drop these into your custom #controls, #slide, or #slideOverlay templates. Pass the dimensions and callbacks through from the slot scope so autoplay, poster capture, and sound sync keep working.

CloseButton

Standalone circular close button with default reel-player styling. Use inside #controls.

SoundButton

Mute/unmute toggle. Render it inside a SoundProvider (ReelPlayerOverlay provides one). Hidden when the active slide has no video.

TimelineBar

Default playback scrub bar. Reads from the nearest TimelineProvider (automatically mounted inside ReelPlayerOverlay) and renders the track, buffered ranges, progress fill, and scrub pill. Theme via the --rk-reel-timeline-* custom properties, or replace via the #timeline slot.

SlideOverlay

The default gradient overlay showing author, description, and likes. Renders when content carries those fields. Replace or hide it via the #slideOverlay slot.

ImageSlide

Image slide with lazy loading and object-fit: cover by default. Compose it inside the #slide slot to customize image rendering while keeping built-in behavior.

VideoSlide

Video slide backed by a shared <video> element. Handles iOS sound continuity, poster frames, and position memory. Render it inside a SoundProvider (ReelPlayerOverlay provides one).

Content Loading & Error Handling

The player tracks per-slide loading and error states. A wave loader shows while content loads; broken media shows an error icon. The player caches failed URLs, so reopening a broken slide skips the retry.

Lifecycle Callbacks

When using the #slide slot, call these callbacks from the slot scope to drive the loading indicator:

Custom Loading & Error UI

Replace the default wave loader and error icon via the #loading and #error slots:

Timeline

The overlay renders a built-in playback timeline bar over the active video. Gate it via the timeline prop: 'auto' (default) renders whenever the active media is a video longer than timelineMinDurationSeconds (default 30), 'always' whenever a video is active, 'never' to disable. For a fully custom scrub bar, use the #timeline slot; its scope exposes a timelineState backed by the underlying TimelineController.

Theme via the --rk-reel-timeline-* CSS custom properties.

Sound Context

ReelPlayerOverlay mounts a SoundProvider at its root, so any component rendered inside can read or toggle mute state via useSoundState. The composable re-exports from @reelkit/vue-reel-player so you don't need a separate @reelkit/vue import.

CSS Classes

CSS classes are plain (not scoped). A stylesheet loaded after @reelkit/vue-reel-player/styles.css can override any of them with a higher-specificity selector. For color, size, and z-index changes, use the CSS custom properties in the Theming section below.

Theming

Every color, size, z-index, and transition lives in a CSS custom property. Override one or many at :root (or any ancestor of the overlay) to retheme without touching component source. The tokens match @reelkit/react-reel-player, so overrides port between bindings.

Drop the snippet below into a stylesheet loaded after @reelkit/vue-reel-player/styles.css.

Accessibility

The overlay root is a modal dialog (role="dialog", aria-modal="true"). Set the aria-label prop to change the screen-reader announcement; it defaults to "Video player". Each slide carries role="group", aria-roledescription="slide", and aria-label="Slide N of M".

The overlay captures focus on open and returns it to the trigger on close. Tab and Shift+Tab cycle through focusable elements inside; focus that escapes (click outside, programmatic focus) gets pulled back. Implemented with captureFocusForReturn and createFocusTrap from @reelkit/core.