React API Reference

Complete reference for @reelkit/react components, props, and methods.

Reel Props

ReelProps

Callbacks

ReelApi Methods

Access slider methods via apiRef:

const apiRef = useRef<ReelApi>(null);

// Navigation
apiRef.current?.next();
apiRef.current?.prev();
apiRef.current?.goTo(5);           // instant
apiRef.current?.goTo(5, true);     // animated

// Lifecycle
apiRef.current?.adjust();          // recalculate positions
apiRef.current?.observe();         // start observing keyboard
apiRef.current?.unobserve();       // stop observing keyboard

ReelIndicator Props

ReelIndicatorProps

Observer Components

Observe

Bridges core signals to React rendering without causing parent re-renders. Only the children function re-executes when subscribed signals change.

import { Observe } from '@reelkit/react';

<Observe signals={[controller.state.index]}>
  {() => <span>Current: {controller.state.index.value}</span>}
</Observe>

AnimatedObserve

Subscribes to animated value signals and smoothly interpolates using requestAnimationFrame.

import { AnimatedObserve } from '@reelkit/react';

<AnimatedObserve signal={controller.state.axisValue}>
  {(value) => (
    <div style={{ transform: `translateY(${value}px)` }} />
  )}
</AnimatedObserve>

SwipeToClose

<SwipeToClose> wraps its children in a container that follows a vertical swipe and calls onClose once the swipe passes the threshold — the dismiss gesture of the lightbox and the stories player, for a custom overlay of your own. SwipeToCloseProps types its props; SwipeToCloseDirection is 'up' | 'down'.

SoundProvider

<SoundProvider> creates one SoundController, muted at first, and hands it to its children through useSoundState. The overlays render one for you; add your own only around a custom player whose controls share a mute state.

Hooks

useBodyLock

Locks body scroll and compensates for scrollbar width shift.

import { useBodyLock } from '@reelkit/react';

// Lock body scroll when overlay is open
useBodyLock(isOpen);

useOverlayUrlState

OverlayUrlStateOptions

Builds a URL-state controller for an overlay, which you hand to a *UrlOverlay as its controller prop.

See URL State in the React guide for the walkthrough and examples.

useReactRouterUrlAdapter

A UrlAdapter backed by React Router. Pass it as the adapter option of useOverlayUrlState in a routed app so the router stays the single source of navigation truth — writing history.pushState behind the router leaves its location stale and its next navigation drops the parameter. Writes touch the query only, so the pathname and hash ride along untouched. Every change reports whether the router pushed on the same page, replaced, or stepped through history, so a gallery opened from a <Link> closes with one back step.

Ships from its own subpath, so an app without a router never pulls react-router-dom into its bundle. react-router-dom is an optional peer dependency.

import { useReactRouterUrlAdapter } from '@reelkit/react/react-router-url-adapter';

const adapter = useReactRouterUrlAdapter();
const photo = useOverlayUrlState({
  param: 'photo',
  adapter,
  ...urlIndexKey(() => images.length),
});

useReelContext

useReelContext() reads the ReelContextValue of the nearest parent <Reel>, or returns null outside one. <ReelIndicator> uses it to connect itself; use it in your own controls rendered as <Reel> children, so they follow the slider without props. ReelContext is the context object behind it — provide a value of your own only in a test or a custom wrapper.

useSoundState

useSoundState() reads the SoundController from the nearest <SoundProvider> and throws outside one. The reel player, lightbox and stories player wrap their content in a provider, so custom controls you pass through their render props can call it to read or toggle mute.

useFullscreen

useFullscreen({ ref }) drives the Fullscreen API for the element in ref, and exits fullscreen when the component unmounts. UseFullscreenProps is its argument; UseFullscreenResult is the tuple it returns.

Accessibility

<Reel> renders as role="region" with aria-roledescription="carousel". Set the ariaLabel prop to give the region a screen-reader name. A polite live region announces "Slide N of M" on every slide change without re-rendering the carousel. Inactive slides receive the inert attribute so focus and AT navigation skip them.

<ReelIndicator> renders as role="tablist" with roving tabindex on the dots; arrow keys move focus and Enter or Space activates the slide.

Building a custom modal around <Reel>? captureFocusForReturn, createFocusTrap, and getFocusableElements are re-exported from @reelkit/react for focus return and trap.

Utilities

createDefaultKeyExtractorForLoop

Creates a key extractor that handles duplicate indexes when loop is enabled.

import { createDefaultKeyExtractorForLoop } from '@reelkit/react';

<Reel
  count={items.length}
  size={size}
  loop
  keyExtractor={createDefaultKeyExtractorForLoop(items.length)}
  itemBuilder={...}
/>

Size detection

observeElementSize, getViewportSize, observeViewportSize, isMobileWidth, fitAspectRatio, and isTouchDevice are re-exported from @reelkit/react, for a custom overlay that sizes itself the way the reelkit ones do. See Size Detection in the core API.

Autoplay and download

createTimerController, createSlideshowController, and downloadFile are re-exported from @reelkit/react too: the timer behind the stories players, the slideshow behind the lightbox's autoAdvance, and the helper behind its download button. See Autoplay and Download in the core API.