Stories Player

Features

Installation

Don't forget to import the styles:

Quick Start

The StoriesOverlay component renders a full-screen stories player. Pair it with StoriesRingList for Instagram-style entry points. Pass an array of StoriesGroup objects and control visibility with isOpen.

Live Demo

PreviewCode

StoriesPlayer.tsxStackBlitz

Alice

Bob

Charlie

Click a story ring to open the player. Tap left/right sides to navigate, swipe to switch users.

API Reference

StoriesOverlayProps

Callbacks

Transitions

The groupTransition prop controls the 3D transition effect when swiping between user groups. Import transition functions from @reelkit/react:

Content Loading Lifecycle

Each story slide communicates its loading state via callbacks provided through SlideRenderProps:

Render Props

Every UI element can be replaced via render props. Each receives typed props with all necessary state and callbacks.

renderHeader

Replace the default header (author info, pause/mute buttons, close button):

renderFooter

Add a footer below the story content:

renderSlide

Fully replace the default image/video slides. Use ImageStorySlide and VideoStorySlide sub-components for built-in media handling:

renderNavigation

Replace the default desktop chevron buttons:

renderProgressBar

Replace the default canvas progress bar with a custom implementation. The progress signal emits values from 0 to 1:

renderLoading

Custom loading indicator while content is being fetched:

renderError

Custom error overlay when content fails to load:

StoriesApi

Use the apiRef prop for imperative control:

Methods

Double-Tap & Likes

A built-in heart animation plays on double-tap, giving instant visual feedback. The onDoubleTap callback fires with the group and story index so you can persist the like in your own state (API call, local storage, etc.). The player does not manage like state internally.

Customizing the Heart Animation

Tweak the animation speed via the --rk-stories-heart-duration token (see Theming). For color, size, or hiding the heart entirely, target the .rk-stories-heart class directly. The HeartAnimation component is also exported for standalone use.

Sub-Components

Reusable building blocks exported for composition in custom render props:

CanvasProgressBar

High-performance canvas-based segmented progress bar. Renders segments for each story and animates the active segment fill via requestAnimationFrame. Supports a sliding window for groups with many stories.

StoryHeader

Default header with author avatar, name, verified badge, relative timestamp, pause/play toggle, mute/unmute toggle, loading spinner, and close button. Used automatically when renderHeader is not provided.

ImageStorySlide

Full-bleed image slide with object-fit: cover. Reports load/error via callbacks for lifecycle tracking.

VideoStorySlide

Video slide using a shared <video> element for iOS sound continuity. Handles autoplay, poster frames, sound sync, and reports duration and playback lifecycle events.

StoriesRing

Circular avatar with an Instagram-style gradient ring. Segments indicate viewed/unviewed stories — gradient for unviewed, muted gray for viewed.

StoriesRingList

Horizontal scrollable row of StoriesRing components with author names. One ring per group.

HeartAnimation

Animated heart overlay triggered on double-tap. Scales up and fades out over 800ms. Customize via CSS (see Double-Tap & Likes section).

Types

StoryItem

AuthorInfo

StoriesGroup<T>

HeaderRenderProps<T>

FooterRenderProps<T>

SlideRenderProps<T>

NavigationRenderProps

ProgressBarRenderProps<T>

LoadingRenderProps<T>

ErrorRenderProps<T>

StoriesApi

Custom Story Types

Extend StoryItem with custom fields and pass the type parameter to StoriesOverlay. All render props will receive your extended type:

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-stories-player/styles.css. For color, size, and z-index changes, prefer the CSS custom properties documented 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.

Drop the snippet below into a stylesheet loaded after @reelkit/react-stories-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 "Stories player".

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.