React API Reference

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

Reel Props

Prop	Type	Default	Description
count	number	required	Total number of items
size	[number, number]	-	Width and height as [width, height]. When omitted, auto-measures via ResizeObserver
itemBuilder	(index, indexInRange, size) => ReactElement	required	Function to render each slide
direction	'vertical' \| 'horizontal'	'vertical'	Scroll direction
initialIndex	number	0	Starting index
loop	boolean	false	Enable infinite loop
enableWheel	boolean	false	Enable mouse wheel navigation
wheelDebounceMs	number	200	Wheel event debounce in ms
enableNavKeys	boolean	true	Enable keyboard navigation
onNavKeyPress	(increment: -1 \| 1) => void	-	Custom handler for arrow key navigation. Replaces default prev/next behavior.
transition	TransitionTransformFn	slideTransition	Transition effect function. Built-in: slideTransition, fadeTransition, flipTransition, cubeTransition, zoomTransition
transitionDuration	number	300	Animation duration in ms
enableGestures	boolean	true	Enable touch/mouse drag navigation
swipeDistanceFactor	number	0.12	Swipe threshold (0-1)
rangeExtractor	(index: number, count: number) => number[]	defaultRangeExtractor	Custom function to determine which indexes are rendered
keyExtractor	(index: number) => string	-	Custom key function for React reconciliation (useful with loop)
apiRef	RefObject<ReelApi>	-	Ref to access API methods
className	string	-	CSS class for the container element
style	CSSProperties	-	Inline styles for the container element
ariaLabel	string	-	Accessible label for the carousel region, read by screen readers

Callbacks

Prop	Type	Description
afterChange	(index, indexInRange) => void	Called after slide change completes
beforeChange	(index, nextIndex, indexInRange) => void	Called before slide change starts
onSlideDragStart	(index) => void	Called when drag gesture starts
onSlideDragEnd	(index) => void	Called when drag gesture ends
onSlideDragCanceled	(index) => void	Called when drag is canceled

ReelApi Methods

Access slider methods via apiRef:

typescript

Method	Type	Description
next()	() => void	Go to next slide
prev()	() => void	Go to previous slide
goTo(index, animate?)	(number, boolean?) => Promise	Go to specific slide
adjust()	() => void	Recalculate slide positions
observe()	() => void	Start keyboard observation
unobserve()	() => void	Stop keyboard observation

ReelIndicator Props

Prop	Type	Default	Description
count	number	auto	Total number of items. Auto-connected from parent Reel when nested inside one; pass explicitly when used standalone
active	number	auto	Current active index. Auto-connected from parent Reel when nested inside one; pass explicitly when used standalone
direction	'vertical' \| 'horizontal'	'vertical'	Indicator orientation
radius	number	3	Dot size in pixels
visible	number	5	Max normal-sized dots visible
gap	number	4	Space between dots in pixels
activeColor	string	'#fff'	Active dot color
inactiveColor	string	'rgba(255,255,255,0.5)'	Inactive dot color
edgeScale	number	0.5	Scale for overflow edge dots
onDotClick	(index: number) => void	-	Callback when a dot is clicked
className	string	-	Custom CSS class
style	CSSProperties	-	Custom inline styles

Observer Components

Observe

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

tsx

AnimatedObserve

Subscribes to animated value signals and smoothly interpolates using requestAnimationFrame.

tsx

Hooks

useBodyLock

Locks body scroll and compensates for scrollbar width shift.

typescript

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.

tsx