Angular Guide

rk-reel Component

The rk-reel component wraps the core slider controller. Standalone, with ChangeDetectionStrategy.OnPush.

Auto-sizing

The size input is optional. When omitted, rk-reel auto-measures its container via ResizeObserver and adapts to CSS-driven layout. The container must be sized by its parent (e.g. flex, grid, or explicit CSS dimensions).

rkReelItem Template Pattern

Instead of React's render prop, Angular uses a structural directive rkReelItem on an ng-template. This enables virtualization — only visible slides are instantiated. The template context provides three variables:

Navigation

Built-in navigation methods:

• Touch/Swipe: Drag to navigate with momentum and snap
• Keyboard: Arrow keys and Escape
• Mouse Wheel: Enable with [enableWheel]="true"
• Programmatic: Use the (apiReady) output to obtain next(), prev(), goTo()

URL State

createOverlayUrlState builds a URL-state controller for an overlay and returns it whole, then you hand it to a *UrlOverlay component as its [controller] input. Call it in an injection context — a field initialiser; it attaches immediately and releases through DestroyRef. The URL owns the open state, so a bound overlay opens itself and a link is the usual open action. The first write of an absent parameter pushes one history entry and every write after replaces it, so paging never buries the back button. Keep the controller to read value/position and to drive it programmatically: set(position) opens, set(null) closes, and set is the same low-level write the overlay uses internally on slide change.

Routed app — pass a Router-backed adapter, otherwise the Router's own location goes stale and its next navigation drops the parameter:

The options object takes param, codec, and locator (all three required), plus an optional adapter. codec and locator are a matched pair sharing the same Id, so a plain ?photo=3 gallery spreads ...urlIndexKey(() => images().length), which returns both halves at once. urlIndexKey bounds the index against the live count the getter returns, so a stale ?photo=99 is rejected and heals itself out of the URL instead of opening a slide that was never named. A paginated feed or an identity-keyed gallery supplies its own matched codec + locator instead. The full options table lives on the Angular API reference.

ReelIndicator

Optional component that displays Instagram-style progress indicators showing the current position in the slider. When placed inside a rk-reel, it auto-connects to the parent's count and active values via the RK_REEL_CONTEXT injection token — no manual wiring needed.

apiReady Output — Signal-Based Pattern

The (apiReady) output fires once after the component is mounted and measured. It emits a ReelApi object you can store and use for imperative navigation. Using Angular signals for this reference works cleanly with OnPush change detection.

Key Points

• Standalone component

  Import ReelComponent, RkReelItemDirective, and optionally ReelIndicatorComponent directly into your component's imports array

• ng-template + rkReelItem

  The Angular equivalent of React's itemBuilder prop — enables virtualization

• apiReady

  Output that fires once with the imperative navigation API — no ViewChild querying required

• afterChange

  Emits { index, indexInRange } — track current index for UI updates

• OnPush by default

  All components use ChangeDetectionStrategy.OnPush and Angular signals for maximum performance

Performance Tips

• Keep slide templates lightweight

  The rkReelItem template runs for each visible slide (typically 3 at a time). Avoid heavy computation or deeply nested structures inside it.

• Load data near the edge

  Use (afterChange) to detect when the user approaches the end and fetch the next batch before slides run out — enabling infinite scroll feeds.

• Use signals for imperative state

  Store the ReelApi reference and current index in Angular signals to get fine-grained reactivity without triggering full component re-renders.

• Disable wheel in scrollable pages

  Set [enableWheel]="false" when the slider is embedded in a scrollable layout to avoid capturing the page scroll.