Reel Player

Features

Installation

Don't forget to import the styles:

Quick Start

The ReelPlayerOverlay component renders a full-screen player overlay. Pass an array of ContentItem objects and control visibility with isOpen.

Live Demo

PreviewCode

ReelPlayerPage.tsxStackBlitz

2

Click a thumbnail to open the full-screen player. Press Escape or the close button to return.

Customization

Generic Content Type

Use custom data types by extending BaseContentItem:

Custom Slide Overlay

Replace the built-in slide overlay with custom content per slide:

Non-Media Slides

Use renderSlide to inject custom content (e.g., CTA cards). Return null to fall back to default:

Custom Controls

Compose reusable sub-components with your own additions:

Custom Timeline

Replace the built-in playback bar with your own scrub UI via renderTimeline. The callback only fires when the overlay's gating rules would render the default bar (same timeline mode + timelineMinDurationSeconds logic), 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 slide-overlay clearance.

Custom Navigation

Custom Nested Navigation

Replace the left/right arrows inside multi-media slides (horizontal carousel) with custom navigation:

Custom Nested Slides

Customise individual slides inside multi-media carousels with renderNestedSlide. Use props.defaultContent to wrap the default ImageSlide/VideoSlide, or replace it entirely:

URL State

ReelPlayerUrlOverlay is a separate component whose open state lives in the address bar. Build a controller with useOverlayUrlState from @reelkit/react and hand it over as controller: the player opens itself when the parameter names a slide and closes when it goes away. Links are shareable, and the back button closes the player instead of leaving the page.

Full useOverlayUrlState options — param, adapter, codec, locator — live in the React API reference. The walkthrough is in the React guide.

• Opening pushes one history entry. Swiping the feed replaces it, so N swipes add no entries and one back step always leaves the player. Back closes; it does not step slides.
• Back closes only when the player was opened from within the app — the link pushed an entry. A shared link opened directly in a fresh tab has no history behind it, so browser-back leaves the site; the ✕ button or Escape removes the parameter in place and stays.
• A deep link ?reel=3 opens the player at that slide on load.
• A parameter naming no slide — a stale bookmark, a hand-edited value — is dropped from the URL rather than leaving the address bar asserting a slide that cannot open.
• By default the parameter addresses the vertical post only (?reel=3). Opt into a two-axis key to also carry the inner media index of a multi-media carousel — see below.

One key or two — pick your URL depth

The same ReelPlayerUrlOverlay drives either shape; it discriminates at runtime from the controller's position, so there is no mode prop. Choose the key when you build the controller:

The two wires are deliberately distinct — a two-axis key is strictly dotted (3.0, never a bare 3), so a bare one-axis link does not cross-decode. Switching an app between keys therefore invalidates any previously shared links. Pick one shape and keep it.

Routed app — pass an adapter. Writing history.pushState behind a router leaves its location stale, and its next navigation drops the parameter:

Stable links. The index is positional, so a bookmarked ?reel=3 opens a different post once the feed is reordered — for a feed that is the normal case, not the exception. urlStableIdKey keys by each post's stable id, scanning the live feed — one call covers the common case.

Pass hashCodec: base64UrlCodec to base64url-encode the id in the URL — reversible obfuscation, not a cryptographic hash.

Key by a different field (a slug), or page an infinite feed with locateAsync, and build the codec/locator yourself. Two separate jobs: codec spells the identity into the URL, locator finds where that identity sits.

Infinite feeds. locate is synchronous, so it can only answer for posts already loaded — a shared link to post 400 of a feed that has loaded 20 comes up empty. locateAsync is the fallback, called only when locate misses.

• While locateAsync is pending the player stays closed and the parameter is left alone, so the deep link survives the fetch. null or a rejection drops the parameter.
• An answer arriving after the URL moved on, after a close, or after unmount is discarded — a slow fetch cannot open a slide nobody asked for.
• Nothing is rendered while pending; the page already owns that loading state, so render your own skeleton.
• There is no timeout — the player cannot know how long the feed is. Settle with null when pagination is exhausted, or the overlay stays closed indefinitely.

API Reference

ReelPlayerOverlayProps Props

ReelPlayerOverlayProps<T>

ReelPlayerUrlOverlay Props

ReelPlayerUrlOverlayProps<T>

Takes every visual and behaviour prop above except isOpen, replaced by a controller. initialIndex is ignored — the controller's position picks the slide, so a value passed alongside it is overwritten on every open.

Callbacks

Reel Props (proxied)

These props are forwarded to the underlying Reel component.

Types

BaseContentItem

The generic constraint type. Extend this to use custom data types with ReelPlayerOverlay.

ContentItem

MediaItem

MediaType

ControlsRenderProps<T>

NavigationRenderProps

SlideRenderProps<T>

NestedSlideRenderProps

SlideOverlayProps

ImageSlideProps

VideoSlideProps

CloseButtonProps

SoundButtonProps

TimelineBarProps

TimelineRenderProps<T>

Sub-Components

Reusable building blocks exported for composition in custom render props:

CloseButton

Standalone close button with default reel-player styling. Use inside renderControls.

SoundButton

Standalone sound toggle. Must be inside a SoundProvider (automatically provided by ReelPlayerOverlay).

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

SlideOverlay

The default gradient overlay showing author, description, and likes. Rendered automatically when content has the required fields. Use renderSlideOverlay to replace or hide it.

ImageSlide

Image slide with lazy loading and object-fit: cover by default. Use inside renderSlide to compose custom image slides with your own styles.

VideoSlide

Video slide with shared <video> element for iOS sound continuity, poster frames, position memory, and loading indicator. Must be inside a SoundProvider (automatically provided by ReelPlayerOverlay).

Content Loading & Error Handling

The player tracks per-slide loading and error states. A wave loader shows while content loads; an error icon shows for broken media. Errored URLs are cached so revisiting shows the error instantly without retrying.

Lifecycle Callbacks

When using renderSlide, call these callbacks to control the loading indicator:

Custom Loading & Error UI

Replace the default wave loader and error icon with custom components:

Timeline

The overlay renders a built-in playback timeline bar over the active video. The timeline prop gates rendering:

• 'auto' (default): renders when the active media is a video whose duration exceeds timelineMinDurationSeconds (default 30). Works for single-video slides and multi-media carousels; the bar follows the active nested item and hides on images.
• 'always': renders whenever the active slide has a video.
• 'never': never renders. Build a custom bar via renderTimeline.

Theme via the --rk-reel-timeline-* CSS custom properties (height, colors, cursor size). For a fully custom scrub bar, timecode, or progress indicator, use renderTimeline; the callback receives a timelineState backed by the underlying TimelineController.

Sound Context

For custom implementations, you can access the sound state:

CSS Classes

All CSS classes are plain (not CSS modules), so they can be targeted with higher-specificity selectors in a stylesheet loaded after @reelkit/react-reel-player/styles.css. For color, size, and z-index changes, prefer the CSS custom properties documented in the Theming section below — they're designed for exactly that.

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.

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

Accessibility

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

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.