React Guide

Reel Component

The Reel component is the main container that manages slider state, handles touch gestures, keyboard navigation, and animations.

Auto-sizing

The size prop is optional. When omitted, Reel auto-measures its container via ResizeObserver and adapts to CSS-driven layout. The container must be sized by its parent (e.g. flex, grid, or explicit CSS dimensions).

itemBuilder Pattern

The itemBuilder prop is a function that receives the index and returns the content for each slide. This pattern enables virtualization — only visible items are rendered.

Navigation

Built-in navigation methods:

• Touch/Swipe: Drag to navigate with momentum and snap
• Keyboard: Arrow keys and Escape
• Mouse Wheel: Enable with enableWheel prop
• Programmatic: Use apiRef for next(), prev(), goTo()

URL State

useOverlayUrlState builds a URL-state controller for an overlay and returns it whole, then you hand it to a *UrlOverlay as its controller prop. The URL owns the open state, so a bound overlay opens itself and a link is the usual open action. The first write of an absent parameter pushes one history entry and every write after replaces it, so paging never buries the back button. Keep the controller to read value/position and to drive it programmatically: set(position) opens, set(null) closes, and set is the same low-level write the overlay uses internally on slide change.

The options object takes param, codec, and locator (all three required), plus an optional adapter. The codec and locator are a matched pair sharing the same Id, so they travel together — for a plain ?photo=3 gallery spread ...urlIndexKey(() => images.length), which returns both halves at once. urlIndexKey maps the parameter to a slide index and bounds it against the live count the getter returns, so a stale or out-of-range ?photo=99 is rejected and heals itself out of the URL instead of opening a slide that was never named. Pass a getter, not a number, so the bound stays right as a paginated feed grows. It wraps createIndexLocator (the locator half) and pairs it with indexCodec. A paginated feed or an identity-keyed gallery supplies its own matched codec + locator instead. The full options table lives on the React API reference.

ReelIndicator

Optional component that displays Instagram-style progress indicators showing the current position in the slider. When placed inside a Reel, it auto-connects to the parent's count and active values via context — no manual state wiring needed.

Live Demo: Basic Slider

Try it — click the buttons to navigate between slides.

Key Points

• size prop

  Optional [width, height] tuple, or omit for auto-sizing via CSS

• itemBuilder

  Receives index and returns the slide content

• apiRef

  Access controller methods for navigation

• afterChange

  Track current index for UI updates

Live Demo: Infinite List

reelkit renders only 3 slides in the DOM at any time (current, previous, next). This allows smooth scrolling for lists with 10,000+ items.

10,000 items — only 3 in the DOM. Use buttons or type a number to jump.

Live Demo: Growable List

Simulates an infinite feed where items load on demand — just like TikTok or Instagram. Start with 20 items, scroll near the end, and watch new batches arrive automatically.

Scroll to the end — new items load automatically. The counter and indicator grow as batches arrive.

Performance Tips

• Memoize data arrays

  Wrap your items array with useMemo. A new array reference on every render triggers a count update and re-computation of visible ranges.

• Keep itemBuilder lightweight

  It runs on every visible range change (typically 3 slides). Avoid heavy computation or side effects inside it.

• Load data near the edge

  Use afterChange to detect when the user approaches the end and fetch the next batch before they run out of slides (see Growable List demo above).

• Disable wheel in scrollable pages

  Set enableWheel={false} when the slider is embedded in a scrollable layout to avoid capturing the page scroll.