Angular Reel Player

Features

Installation

Basic Usage

Import the stylesheet and the standalone RkReelPlayerOverlayComponent into your component's imports array.

Template Slots

Six template slot directives let you customize every aspect of the player's UI. Each receives a strongly-typed context object. Only provide the slots you want to override — the defaults are used for the rest.

Custom Timeline

The rkPlayerTimeline template slot is invoked 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. Call state.bindInteractions(el) on your scrub track to wire pointer + keyboard scrubbing.

Nested Slider (Multi-Media Items)

When a ContentItem contains multiple media entries, the player renders them in a horizontal nested slider (Instagram carousel style). Use the rkPlayerNestedSlide slot to customize the inner slide content.

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 the rkPlayerSlide template slot, use the context callbacks to control the loading indicator:

Custom Loading & Error UI

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

Timeline

The overlay renders a built-in playback timeline bar over the active video. Gate it via the timeline input: '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 rkPlayerTimeline template directive; its context exposes a timelineState backed by the underlying TimelineController.

Theme via the --rk-reel-timeline-* CSS custom properties. For direct control in custom consumer components, inject TimelineStateService.

RkTimelineBarComponent

Default playback scrub bar component. Consumes TimelineStateService (provided by RkReelPlayerOverlayComponent) and renders the track, buffered ranges, progress fill, and scrub pill. Selector: rk-timeline-bar. Inputs: class?: string, style?: Record<string, string>. Use inside an rkPlayerTimeline template to wrap or augment the default bar; use standalone only inside a consumer that provides the service.

SoundStateService

Provided at the RkReelPlayerOverlayComponent level. Injected by the default sound button and exposed in the controls template slot context. Can be injected in custom controls that are children of the overlay for direct access.

URL State

RkReelPlayerUrlOverlayComponent is a separate component whose open state lives in the address bar. Build a controller with createOverlayUrlState in an injection context and pass it as [controller]: the player opens when the parameter names a slide and closes when it goes away. Links are shareable, and the back button closes the player. RkReelPlayerOverlayComponent stays [isOpen]-controlled, so each component carries exactly one open-state driver.

A routed app passes a Router-backed adapter, so the Router stays the single source of navigation truth — writing history behind it leaves its location stale and drops the parameter on the next navigation. createRouterUrlAdapter from @reelkit/angular/ng-router-url-adapter is the ready-made adapter.

• 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.
• The URL depth follows the controller’s key: one-axis for the post only, or two-axis (urlIndexTwoAxisKey) to also carry a multi-media post’s inner image index. Pick one key per app; the shapes do not cross-decode.

Full createOverlayUrlState options are on the Angular API reference.

One key or two — pick your URL depth

The same RkReelPlayerUrlOverlayComponent drives either shape; it discriminates at runtime from the controller’s position, so there is no mode input. 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.

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. 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: load the pages you need, then return the index the identity turned out to have.

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

Custom Data Types

Extend BaseContentItem to use your own domain model. The component is generic: RkReelPlayerOverlayComponent<T extends BaseContentItem>.

RkReelPlayerOverlayComponent Inputs

RkReelPlayerOverlayComponent Outputs

RkReelPlayerUrlOverlayComponent Inputs

Takes every input above except isOpen and initialIndex, replaced by a controller whose position picks the slide. Outputs closed and slideChange.

MediaItem Interface

Template Slot Context Types

CSS Classes

All CSS classes are plain (not scoped), so they can be targeted with higher-specificity selectors in a stylesheet loaded after @reelkit/angular-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. The tokens match the React and Vue packages, so overrides port between bindings.

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

Accessibility

The overlay root is a modal dialog (role="dialog", aria-modal="true"). Set the ariaLabel input 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.