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:

API Reference

Props

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.