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>

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),
});

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={...}
/>