Complete reference for @reelkit/core configuration, callbacks, methods, and state.
SliderController API
The framework-agnostic core. One factory builds a controller from a config and optional events: Config Options are the config, Callbacks the events, and Methods are what the returned controller exposes.
Run side effect when any dependency signal changes; returns dispose function. Read signal values inside the effect callback.
batch
(fn: () => void) => void
Group multiple signal updates into a single notification pass; supports nesting
Listener
() => void
The callback observe takes. Type a signal observer you declare separately with it.
Dispose
() => void
What observe and reaction return: call it to stop listening. Type a stored subscription with it.
Transitions
Built-in transition functions that compute per-slide CSS transforms during animated navigation. Pass one as the transitionTransformFn prop to the framework component.
Export
Type
Description
TransitionTransformFn
type
Signature for custom transition functions
getSlideProgress
(axisValue: number, slideIndex: number, primarySize: number) => number
Returns a normalized offset (-1 to 1) for a slide relative to the viewport. Use inside custom transition functions.
What a TransitionTransformFn returns for one slide. Return it from a custom transition.
Input Controllers
The slider controller builds these three itself from its enableGestures, enableNavKeys and enableWheel options. Create one directly when you write your own integration, or need gestures, arrow keys or the wheel on an element that is not a slider.
Object createGestureController returns. attach(element) binds the element, observe() adds the listeners, unobserve() removes them and keeps the element, detach() removes everything; updateEvents(events) merges new handlers in.
Payload of onHorizontalDragUpdate and onVerticalDragUpdate: movement since the last update, total distance, the same along the dominant axis, and cancel() to snap the drag back.
GestureAxisDragEndEvent
GestureAxisDragUpdateEvent without cancel, plus { velocity; primaryVelocity }
Payload of onHorizontalDragEnd and onVerticalDragEnd, with the release speed in pixels per second.
GestureDragEndEvent
GestureAxisDragEndEvent without the primary fields
Payload of onDragEnd, for a handler that does not care which axis the drag took.
Offset
[x: number, y: number]
A pixel pair, used for every position, delta, distance and velocity in a gesture event.
EventKind
'touch' | 'mouse'
The input a gesture came from, in the kind field of GestureCommonEvent.
DragAxis
'horizontal' | 'vertical' | null
The dominant axis of a drag, null until the first movement decides it.
Callback createWheelController calls once per scroll gesture.
WheelDirection
'up' | 'down' | 'left' | 'right'
The direction of a wheel gesture.
Content Loading
Utilities for tracking per-slide loading/error states and preloading media. The loading controller uses an index guard to reject stale callbacks from previously active slides. The preloader uses an LRU cache (default 200 loaded, 100 errored) so revisiting a broken URL shows the error instantly without retry.
Observes video loading state (playing, canplaythrough, waiting). Returns a disposer.
ContentLoadingController
Export
Type
Description
isLoading
Signal<boolean>
Whether the active slide is loading
isError
Signal<boolean>
Whether the active slide has errored
setActiveIndex
(index: number) => void
Update active index, resets loading/error state
onReady
(index: number) => void
Mark slide as ready (ignored if index doesn't match active)
onWaiting
(index: number) => void
Mark slide as loading (ignored if index doesn't match active)
onError
(index: number) => void
Mark slide as errored (ignored if index doesn't match active)
ContentPreloader
Export
Type
Description
preload
(src: string, type?: "image" | "video") => void
Start preloading a media URL
isLoaded
(src: string) => boolean
Check if URL is in the loaded LRU cache (max 200)
isErrored
(src: string) => boolean
Check if URL is in the error LRU cache (max 100)
markLoaded
(src: string) => void
Manually mark a URL as loaded
markErrored
(src: string) => void
Manually mark a URL as errored
onLoaded
(src: string, cb: () => void) => () => void
Subscribe to load completion; returns disposer
Sound
Shared mute/unmute state for media playback. The sound controller provides a reactive muted signal that can be synced to video elements and toggled from custom controls.
Syncs the muted signal to a video element. Returns a disposer.
Timeline
Playback timeline controller for video scrubbing. Tracks duration, current time, buffered ranges, and user scrubbing state as reactive signals. A single call wires pointer and keyboard interactions onto any DOM element so it behaves as a native-feeling scrub bar, with pointer capture, live seeking, and full keyboard support (arrows, Home/End, PageUp/PageDown).
Factory returning a controller with duration, currentTime, progress, bufferedRanges, and isScrubbing signals plus attach, detach, bindInteractions, and seek methods.
A single contiguous buffered region expressed as 0–1 fractions of total duration. Emitted sorted and non-overlapping.
Fullscreen
Cross-browser fullscreen utilities with Safari vendor-prefix guards. The fullscreen signal is a lazy singleton that tracks fullscreen state reactively.
Export
Type
Description
fullscreenSignal
Signal<boolean>
Reactive signal tracking whether the document is in fullscreen mode
requestFullscreen
(element: HTMLElement) => Promise<void>
Enter fullscreen on the given element
exitFullscreen
() => Promise<void>
Exit fullscreen mode
DOM & Cleanup Utilities
Low-level helpers for DOM event management and deterministic cleanup. Used internally by all controllers and available for custom integrations.
Export
Type
Description
observeDomEvent
(target, event, handler, options?) => () => void
Adds a DOM event listener and returns a disposer that removes it
createDisposableList
() => DisposableList
Composable list for collecting disposer functions. Call dispose() to run all at once.
createBodyLock
() => BodyLock
Reference-counted body scroll lock. Multiple consumers can lock simultaneously; scroll is restored when all unlock.
sharedBodyLock
BodyLock
Module-level singleton instance. Use when multiple components across your app should share a single reference counter so nested modals/overlays interleave correctly. Framework bindings (@reelkit/react, @reelkit/vue, @reelkit/angular) use this under the hood.
Utilities
Small helpers the controllers are built from. The framework bindings re-export them, so a custom slide, transition or integration can use the same ones.
Export
Type
Description
first
<T>(arr: readonly T[]) => T
First element of an array, such as the x of an Offset or the width of a size.
last
<T>(arr: readonly T[]) => T
Last element of an array, such as the y of an Offset or the height of a size.
Indexes from start to end (default start) plus overscan on each side (default 1), wrapped around the ends when loop is true. Build a custom RangeExtractor with it.
noop
() => void
A function that does nothing, for a default callback.
createDeferred
<T = void>() => Deferred<T>
A promise together with the resolve that settles it, for bridging a callback API to await.
A Map that keeps the maxSize most recently set entries and drops the oldest past that. onEvict runs for each dropped entry, for cleanup such as URL.revokeObjectURL.
LruCache
Map<string, V>
Object createLruCache returns. It is a real Map; only set differs.
animate
(options: AnimationOptions) => () => void
Animates a number from from to to with an ease-in-out curve, calling onUpdate each frame. Returns a function that cancels the animation.
AnimationOptions
{ from; to; duration; onUpdate; onComplete? }
Options of animate: start and end value, duration in milliseconds, the per-frame callback and an optional callback when it finishes.
Size Detection
How every binding and overlay measures its container and the window. Reel uses observeElementSize when no size is passed; the reel player, lightbox and stories player size themselves from the window. SSR-safe: without a window or ResizeObserver the getters return [0, 0] or false and the observers return a no-op disposer.
Reports the element's padding box (clientWidth × clientHeight) whenever it changes. Skips a size with a zero side (hidden or not laid out yet) and a size equal to the last one reported.
Calls back with the window size on every resize event, including one that leaves the size unchanged (device emulation can switch to a touch device of the same dimensions). Compare sizes yourself if only a change matters.
isMobileWidth
(viewportWidth: number) => boolean
Whether a window this wide gets the phone layout: 768px and narrower. Every overlay and its stylesheet switch at this width.
Overlay size for a window. On a phone width it is the whole window; otherwise the full window height at aspectRatio, narrowed to the window width when that would not fit. A missing, zero, negative or non-finite ratio falls back to 9/16.
isTouchDevice
() => boolean
Whether the device takes touch input (ontouchstart or maxTouchPoints). A capability check, not a screen size: a touch laptop counts, a narrow desktop window does not.
Autoplay
Timers for anything that advances on its own. How they behave and how to wire them is in the Autoplay guide.
The state machine behind a gallery that advances on its own. Drives the lightbox autoAdvance.
createTimerController
TimerControllerConfig
Type
Description
duration
number
Default duration in milliseconds, used when start() gets none
onComplete
() => void
Called when progress reaches 1
TimerController
Type
Description
progress
Signal<number>
Progress from 0 to 1; drives a progress bar
isRunning
Signal<boolean>
Whether the timer is counting
start(duration?)
(number?) => void
Start over from 0, optionally with another duration for this run
pause()
() => void
Freeze at the current progress
resume()
() => void
Continue from the frozen progress
reset()
() => void
Back to 0, stopped
dispose()
() => void
Cancel the pending frame
createSlideshowController
SlideshowControllerConfig
Type
Description
interval
number
How long an image stays, in milliseconds, counted once it has loaded
onAdvance
() => void
The active slide is done. Move to the next slide, or call pause() on the last one
SlideshowController
Type
Description
isPlaying
Signal<boolean>
Whether the slideshow is switched on. Holds do not change it
progress
Signal<number>
How far the active image's interval has run, from 0 to 1
play() / pause() / toggle()
() => void
Switch it on or off; the active slide keeps its progress
setInterval(ms)
(number) => void
Change the interval from the next image
setSlide(kind)
(SlideshowSlideKind) => void
A new slide became active: progress starts over and waits for ready() or ended(). SlideshowSlideKind is 'image' | 'video'
ready()
() => void
The active image loaded or failed to; its interval starts
ended()
() => void
The active video ended; advances now, or once nothing holds
hold(reason) / release(reason)
(string) => void
Stop the clock for a reason such as 'hover' or 'drag'. Holds stack
dispose()
() => void
Stop the clock and the visibility listener
Download
Saving a file from a URL, cross-origin included. The fallback it takes is in the Download guide.
Export
Type
Description
downloadFile
(url: string, filename?: string) => Promise<void>
Saves a file under filename, by default the last segment of the URL's path. It fetches the file and saves the blob, because the download attribute is ignored on a cross-origin link. When the fetch fails or the server answers with an error (a cross-origin server without CORS headers is the usual case), the URL opens in a new tab instead. Never rejects; does nothing without a window.
Focus Management
Framework-agnostic dialog a11y primitives. The overlay packages use them to return focus to the trigger on close and trap Tab / Shift+Tab inside the overlay while it's open. SSR-safe: each helper returns a no-op disposer in non-browser environments.
Export
Type
Description
captureFocusForReturn
() => Disposer
Captures the currently focused element and returns a disposer that focuses it again. Best-effort: the disposer is a no-op if the captured element has since been removed from the DOM.
createFocusTrap
(container: HTMLElement) => Disposer
Traps Tab/Shift+Tab inside container. Tab at the last focusable wraps to the first; Shift+Tab at the first wraps to the last; focus that escapes the container (click outside, programmatic focus) is pulled back. Does not move focus into the container on activation — the caller decides.
getFocusableElements
(container: HTMLElement) => HTMLElement[]
Returns every keyboard-focusable descendant in DOM order, skipping disabled, hidden, and tabindex="-1" elements.
Usage
typescript
import { captureFocusForReturn, createFocusTrap } from '@reelkit/core';// When your modal opens:const restoreFocus = captureFocusForReturn();container.focus({ preventScroll: true });const releaseTrap = createFocusTrap(container);// When the modal closes:releaseTrap();restoreFocus();
Video Utilities
Framework-agnostic utilities for shared video playback across slides. Used internally by @reelkit/react-reel-player and @reelkit/react-lightbox, available for custom framework bindings.
Export
Type
Description
captureFrame
(video: HTMLVideoElement) => string | null
Captures the current video frame as a JPEG data URL. Returns null on cross-origin errors.
Creates a scoped shared video singleton with playback position and frame capture maps. Each consumer gets an isolated instance for iOS sound continuity.
Keeps video.style.objectFit in sync with the video's real orientation. Applies the fallback (from the declared aspect ratio) immediately, then on loadedmetadata reads actual videoWidth / videoHeight and switches to 'cover' for portrait, 'contain' for landscape. Resilient to wrong declared metadata.
URL State
Mirror one query parameter into a signal and back. Two axes, each one job: a codec is the wire (param text ↔ a stable identity), a locator is the lookup (where that identity sits in the collection).
Mirrors one query parameter into a signal and writes changes back to the URL. The first write of an absent parameter pushes one history entry; every write after that replaces it. Given a codec or locator it also derives position: Signal<Pos | null>, applying the open/close latch and self-healing a parameter that names no slide — so every binding subscribes rather than re-deriving. Writing a position while closed opens at once, without waiting for the adapter to report the write back; UrlChange says when a close steps back versus clears in place.
createHistoryAdapter
() => UrlAdapter
Default adapter over the History API. A routed application should inject its own instead, otherwise the router's location goes stale and its next navigation drops the parameter.
indexCodec
UrlCodec<number>
Reads ?photo=3 as slide 3. Pass it to opt into index derivation without writing a codec of your own. For an infinite or paginated list, pass locator instead — the parameter survives while the promise is pending, so a deep link into an unloaded page is not cleared mid-fetch.
createIndexLocator
(countGetter: () => number) => UrlLocator<number>
The default index locator: a slide position maps to itself, bounded by the live count the getter returns. An out-of-range index resolves to null, so a stale ?photo=99 self-heals out of the URL — it rejects rather than coercing to the nearest slide, which would open one the URL never named. A getter, not a number, so the bound reads the current size at lookup time as a paginated gallery grows.
urlIndexKey
(countGetter, locateAsync?) => UrlKey<number>
The matched pair for an index-addressed gallery — indexCodec plus a createIndexLocator bound to the gallery's size. Spread it ({ param, ...urlIndexKey(() => count) }) so the codec cannot drift from the locator. Pass a second locateAsync argument to window a paginated feed — page up to the wanted index on a miss, then return it.
Like urlIndexKey but for a two-axis player: one strictly-dotted ?p=<outer>.<inner> parameter resolving to a TwoAxisPosition{ outer, inner }. Options (UrlIndexTwoAxisKeyOptions): outerCount, innerCounts, optional outerCodec/outerLocator for the outer axis, and innerCodec/innerLocate/innerIdentify to address the inner axis by id too. Each axis defaults to a plain index bound. Powers the URL-driven stories player.
The stable-id wire, exported for composing — the param text is the item's id, written raw or transformed by hashCodec (pass base64UrlCodec for reversible base64url). The stable-id analog of indexCodec: pair it with a locator of your own instead of taking the whole urlStableIdKey.
base64UrlCodec
UrlCodec<string>
The ready-made hash mechanism for a stable-id key: reversible base64url (URL-safe alphabet, no padding, UTF-8) — not a cryptographic hash. Pass it as hashCodec to obscure the id in the URL, or implement your own UrlCodec<string> to plug in a different scheme.
The stable-id lookup, exported for composing — scans items() for a matching id; a gone id resolves to null and self-heals. Optional locateAsync windows a paginated feed. The stable-id analog of createIndexLocator.
urlStableIdKey
(opts) => UrlKey<string, number>
Addresses a gallery by each item's stable id — ?photo=<id> — instead of its position, so a bookmark survives the list being reordered. Options (UrlStableIdKeyOptions): items (a live getter), optional hashCodec (pass base64UrlCodec) to transform the id on the wire, optional locateAsync to window a paginated feed (fetch until the id is present on a miss, then return its index). Prefer over urlIndexKey whenever the list can change under a shared link.
The two-axis analog: the outer axis by stable id, the inner by a local index — ?story=user_42.3. Supply innerItems instead of innerCounts to address the inner by id too (?story=user_42.photo_7); hashCodec (e.g. base64UrlCodec) transforms both ids. Options UrlStableIdTwoAxisKeyOptions (index inner) or UrlStableIdTwoAxisIdInnerOptions (id inner); item types satisfy Identified ({ id: string }).
UrlCodec<Id>
{ decode(raw) => Id | null; encode(id) => string }
The wire format: parameter text ↔ a stable identity, collection-blind. decode returning null means malformed text.
UrlLocator<Id>
{ locate(id) => number | null; locateAsync?(id) => Promise<number | null>; identify(index) => id }
The lookup: where the identity sits in the collection. locate is synchronous, locateAsync its fallback for a paginated list, and identify turns an index back into an identity for writes.
UrlKey<Id>
{ codec: UrlCodec<Id>; locator: UrlLocator<Id> }
The matched codec + locator pair for one parameter. They share the same Id and always travel together — the codec spells the identity into the URL, the locator finds where it sits — so building them as a pair is what keeps them from disagreeing.
The injection point for a router. A routed application must supply one, or the router's own location goes stale. The subscribe listener accepts an optional UrlChange; calling it with nothing is always valid and means the adapter cannot say how the entry came to be current.
UrlChange
{ kind?: 'push' | 'replace' | 'pop' }
What an adapter knows about the navigation that just landed. Report push only for a navigation the router itself made on the same page; that is the one case where closing may pop the entry. With no evidence the entry is never claimed and closing clears the parameter in place, leaving a duplicate of the page in history rather than risking a step off the site.
The options createUrlStateController takes — exported so a consumer can type a config assembled separately before handing it over.
Viewed State
Persist how far a viewer got, keyed the same way the address bar is: an entry is the parameter text itself, read back through the same codec and locator.
Export
Type
Description
createViewedStateController
(options) => ViewedStateController<Pos>
Remembers how far a viewer got, persisted as the very text a URL parameter would carry. Takes the same codec/locator pair the address bar uses, plus storageKey, optional storage, trackOf (one entry per group), and progressOf. Reads nothing until attach(), so it is safe to prerender.
twoAxisViewedTracking
{ trackOf, progressOf }
The tracking pair for a two-axis player: one entry per outer slot, the inner index measuring progress through it. Spread it beside a two-axis key.
createLocalStorageAdapter
() => StorageAdapter
The default backing. Also createSessionStorageAdapter for state that should not outlive the tab, and createMemoryStorageAdapter for tests and server rendering. Every one absorbs its own failures — an exhausted quota loses that write and no more.
entries is a signal of track → stored text, so a ring repaints when a position is recorded here or in another tab. resolve runs the full key cycle on every call.
The options createViewedStateController takes — exported so a consumer can type a config assembled separately before handing it over. progressOf is optional only for a plain index position, which is its own measure of progress; any other position must say which number to compare, and the type requires it. ttlMs opts into expiry: a track is forgotten that long after it was last recorded, and recording it again restarts its clock. maxTracks keeps at most that many tracks, dropping the least recently recorded on the next write.
'/%3e%3c!--%20Motion%20trails%20--%3e%3crect%20x='14'%20y='7'%20width='12'%20height='2'%20rx='1'%20fill='white'%20opacity='.2'/%3e%3crect%20x='12'%20y='12'%20width='16'%20height='2'%20rx='1'%20fill='white'%20opacity='.35'/%3e%3crect%20x='10'%20y='17'%20width='20'%20height='2.5'%20rx='1.25'%20fill='white'%20opacity='.5'/%3e%3c!--%20Bold%20chevron%20down%20--%3e%3cpath%20d='M10%2024%20L20%2034%20L30%2024'%20stroke='white'%20stroke-width='3.5'%20stroke-linecap='round'%20stroke-linejoin='round'%20fill='none'/%3e%3c/svg%3e)