@reelkit/vue-reel-player

@reelkit/vue-reel-player

Instagram Reels / TikTok-style video player for Vue 3. Opens as a full-screen overlay with vertical swipe navigation. Handles video autoplay, sound continuity on iOS, and multi-media posts. ~5.8 kB gzip.

Live Demo

Installation

npm install @reelkit/vue-reel-player @reelkit/vue lucide-vue-next

Quick Start

<script setup lang="ts">
import { ref } from 'vue';
import { ReelPlayerOverlay, type ContentItem } from '@reelkit/vue-reel-player';
import '@reelkit/vue-reel-player/styles.css';

const isOpen = ref(false);
const content: ContentItem[] = [
  {
    id: '1',
    media: [
      {
        id: 'v1',
        type: 'video',
        src: 'https://example.com/video.mp4',
        poster: 'https://example.com/poster.jpg',
        aspectRatio: 9 / 16,
      },
    ],
    author: { name: 'John Doe', avatar: 'https://example.com/avatar.jpg' },
    likes: 1234,
    description: 'Amazing video!',
  },
];
</script>

<template>
  <button @click="isOpen = true">Open Player</button>
  <ReelPlayerOverlay
    :is-open="isOpen"
    :content="content"
    @close="isOpen = false"
  />
</template>

Features

• Vertical swipe navigation (touch, mouse, keyboard, wheel)
• Video autoplay with sound toggle
• Multi-media posts with horizontal nested slider
• Instagram-style indicator dots
• Keyboard navigation (Arrow keys, Escape)
• Desktop navigation arrows
• iOS sound continuity via shared <video> element
• Video position memory across slide changes

Scoped Slots

All of the player's UI is customizable via scoped slots:

Slot	Scope
slide	item, index, size, isActive, slideKey, defaultContent, …
slideOverlay	item, index, isActive
controls	item, soundState, activeIndex, content, onClose
navigation	item, activeIndex, count, onPrev, onNext
nestedSlide	item, media, index, size, isActive, isInnerActive, …
nestedNavigation	media, activeIndex, count, onPrev, onNext
loading	item, activeIndex
error	item, activeIndex

Props

Prop	Type	Default	Description
isOpen	boolean	required	Controls overlay visibility
content	ContentItem[]	required	Content items to display
initialIndex	number	0	Starting slide index
aspectRatio	number	9/16	Desktop container ratio
loop	boolean	false	Enable infinite loop
enableNavKeys	boolean	true	Enable keyboard navigation
enableWheel	boolean	true	Enable mouse wheel navigation
wheelDebounceMs	number	200	Wheel debounce duration (ms)
transitionDuration	number	300	Transition duration (ms)
swipeDistanceFactor	number	0.12	Swipe threshold (0-1)

Events

Event	Payload	Description
close	void	Emitted when player closes
slide-change	number	Emitted after slide change
api-ready	ReelApi	Emitted with imperative API
update:is-open	boolean	Emitted on close — enables v-model:is-open

v-model:is-open

Use it to drive the overlay with a single binding instead of pairing :is-open + @close:

<script setup lang="ts">
import { ref } from 'vue';
const open = ref(false);
</script>

<template>
  <button @click="open = true">Open</button>
  <ReelPlayerOverlay v-model:is-open="open" :content="content" />
</template>

The legacy :is-open + @close pattern still works.

Custom content types

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

<script setup lang="ts">
import { ref } from 'vue';
import {
  ReelPlayerOverlay,
  type BaseContentItem,
  type SlideOverlaySlotScope,
} from '@reelkit/vue-reel-player';

interface MyItem extends BaseContentItem {
  title: string;
  category: 'video' | 'photo';
}

const open = ref(false);
const items: MyItem[] = [
  /* ... */
];
</script>

<template>
  <ReelPlayerOverlay v-model:is-open="open" :content="items">
    <template #slideOverlay="{ item }: SlideOverlaySlotScope<MyItem>">
      <div class="my-overlay">
        <h2>{{ item.title }}</h2>
        <span>{{ item.category }}</span>
      </div>
    </template>
  </ReelPlayerOverlay>
</template>

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

Keyboard Shortcuts

Key	Action
ArrowUp	Previous slide
ArrowDown	Next slide
ArrowLeft	Previous media (nested)
ArrowRight	Next media (nested)
Escape	Close player

Documentation

Docs and interactive demos at reelkit.dev/docs/vue-reel-player.

Support

If ReelKit saved you some time, a star on GitHub would mean a lot — it's a small thing, but it really helps the project get noticed.

License

MIT