Core API Reference

Complete reference for @reelkit/core configuration, callbacks, methods, and state.

Config Options

Property	Type	Default	Description
count	number	required	Total number of items
initialIndex	number	0	Starting index
direction	'vertical' \| 'horizontal'	'vertical'	Scroll direction
enableGestures	boolean	true	Enable touch/mouse drag navigation. When false, the gesture controller is not attached.
enableNavKeys	boolean	true	Enable keyboard arrow key navigation
enableWheel	boolean	false	Enable mouse wheel
wheelDebounceMs	number	200	Wheel debounce time
loop	boolean	false	Loop navigation
transitionDuration	number	300	Animation duration in ms
swipeDistanceFactor	number	0.12	Swipe threshold (0-1)
rangeExtractor	(index: number, count: number, loop: boolean) => number[]	defaultRangeExtractor	Custom function to determine which indexes are rendered

Callbacks

Callback	Type	Description
onBeforeChange	(index, nextIndex, rangeIndex) => void	Before slide change
onAfterChange	(index, rangeIndex) => void	After slide change
onDragStart	(index) => void	Drag started
onDragEnd	(index) => void	Drag ended
onDragCanceled	(index) => void	Drag canceled
onTap	(event: GestureCommonEvent) => void	Single tap (delayed by double-tap window)
onDoubleTap	(event: GestureCommonEvent) => void	Double tap detected
onLongPress	(event: GestureCommonEvent) => void	Long press detected
onLongPressEnd	(event: GestureEvent) => void	Pointer released after long press
onNavKeyPress	(increment: -1 \| 1) => void	Custom handler for arrow key navigation. Replaces default prev/next behavior.

Methods

Method	Type	Description
attach(element)	(HTMLElement) => void	Connect controller to DOM element for gesture detection
detach()	() => void	Detach DOM listeners (gestures, keyboard, wheel). Safe for re-attach via observe(). Use for React effect cleanup.
dispose()	() => void	Permanent teardown: detaches all controllers and cleans up signal observers. Use for Angular onDestroy.
observe()	() => void	Start gesture, keyboard, and wheel observation. Respects enableGestures, enableNavKeys, and enableWheel config flags.
unobserve()	() => void	Stop gesture, keyboard, and wheel observation
next()	() => Promise<void>	Go to next slide
prev()	() => Promise<void>	Go to previous slide
goTo(index, animate?)	(number, boolean?) => Promise<void>	Go to specific slide
adjust(duration?)	(number?) => void	Recalculate slide positions
setPrimarySize(size)	(number) => void	Update container size
updateConfig(config)	(Partial<SliderConfig>) => void	Update configuration options
updateEvents(events)	(Partial<SliderEvents>) => void	Replace event handlers (existing handlers not included are preserved)
getRangeIndex()	() => number	Returns the position of the active index within the visible range array

State Properties

Property	Type	Description
index	Signal<number>	Current slide index
axisValue	Signal<AnimatedValue>	Current axis position value (animated)
indexes	ComputedSignal<number[]>	Visible indexes for virtualization

Range Extractor

Export	Type	Description
defaultRangeExtractor	(index: number, count: number, loop: boolean) => number[]	Default extractor that renders 3 items around current index

Signal API

Lightweight reactive primitives used throughout the core.

Signal Interface

Member	Type	Description
value	T	Get or set the current value. Setting notifies observers if the value changed.
observe(callback)	(callback: () => void) => () => void	Register a listener called on each value change. Returns a dispose function that removes the listener.

Factory Functions

Export	Type	Description
createSignal	<T>(initial: T) => Signal<T>	Create a mutable reactive signal
createComputed	<T>(fn: () => T, deps: () => Subscribable[]) => ComputedSignal<T>	Create a derived computed signal. The second argument is a deps factory that returns the signals to track.
reaction	(deps: () => Subscribable[], effect: () => void) => () => void	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

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.
slideTransition	TransitionTransformFn	Default slide transition (translateX/Y)
fadeTransition	TransitionTransformFn	Crossfade opacity transition
flipTransition	TransitionTransformFn	3D card-flip transition
cubeTransition	TransitionTransformFn	3D cube rotation transition
zoomTransition	TransitionTransformFn	Scale/zoom transition

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.

Export	Type	Description
createContentLoadingController	() => ContentLoadingController	Per-slide loading/error state tracking
createContentPreloader	(config: ContentPreloaderConfig) => ContentPreloader	LRU-cached media preloader with error caching
observeMediaLoading	(video: HTMLVideoElement, callbacks: MediaLoadingCallbacks) => () => void	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.

Export	Type	Description
createSoundController	() => SoundController	Shared mute state controller
syncMutedToVideo	(video: HTMLVideoElement, sound: SoundController) => () => void	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).

Export	Type	Description
createTimelineController	(config?: TimelineControllerConfig) => TimelineController	Factory returning a controller with duration, currentTime, progress, bufferedRanges, and isScrubbing signals plus attach, detach, bindInteractions, and seek methods.
TimelineControllerConfig	interface	keyboardStepSeconds (default 5), keyboardPageFraction (default 0.1), and onSeek, onScrubStart, onScrubEnd callbacks.
BufferedRange	{ start: number; end: number }	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.

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

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.
createSharedVideo	(config: SharedVideoConfig) => SharedVideoInstance	Creates a scoped shared video singleton with playback position and frame capture maps. Each consumer gets an isolated instance for iOS sound continuity.
syncVideoObjectFit	(video: HTMLVideoElement, fallbackIsVertical: boolean) => Disposer	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.