Konstantin Kai

Posted on Mar 16

ReelKit: A Virtualized TikTok-Style Slider Engine

#react #typescript #webdev #opensource

You're building a vertical feed — TikTok-style swipe, full-screen slides, thousands of items. You reach for a carousel library and hit the wall: it renders all slides to the DOM, chokes on touch gestures, and bundles half the internet.

ReelKit renders 3 DOM nodes at any time — previous, current, next — whether you have 4 slides or 40,000. Zero dependencies in core. Touch-first with momentum and snap. ~3.7 kB gzipped.

Try it live on StackBlitz — no setup needed.

Quick start

npm install @reelkit/react

import { useState } from 'react';
import { Reel, ReelIndicator } from '@reelkit/react';

const slides = [
  { title: 'Discover', color: '#6366f1' },
  { title: 'Trending', color: '#8b5cf6' },
  { title: 'Following', color: '#ec4899' },
  { title: 'For You', color: '#14b8a6' },
];

export default function App() {
  const [index, setIndex] = useState(0);

  return (
    <Reel
      count={slides.length}
      style={{ width: '100%', height: '100dvh' }}
      direction="vertical"
      enableWheel
      useNavKeys
      afterChange={setIndex}
      itemBuilder={(i, _inRange, size) => (
        <div
          style={{
            width: size[0],
            height: size[1],
            background: slides[i].color,
            display: 'flex',
            alignItems: 'center',
            justifyContent: 'center',
            color: 'white',
            fontSize: '2rem',
          }}
        >
          {slides[i].title}
        </div>
      )}
    >
      <ReelIndicator count={slides.length} active={index} />
    </Reel>
  );
}

Swipe, keyboard arrows, mouse wheel — all work out of the box. The size prop is optional: omit it and ReelKit auto-measures via ResizeObserver.

Programmatic navigation

const apiRef = useRef<ReelApi>(null);

<Reel count={100} apiRef={apiRef} itemBuilder={(i) => <Slide index={i} />} />

<button onClick={() => apiRef.current?.prev()}>Prev</button>
<button onClick={() => apiRef.current?.next()}>Next</button>
<button onClick={() => apiRef.current?.goTo(50)}>Jump to 50</button>

Navigation methods return promises — await apiRef.current!.next() resolves when the animation completes, so you can chain transitions sequentially.

How it works

Virtualization

Only render what's visible. ReelKit computes a visible range from the current index:

Current index: 50, count: 10,000
Visible: [49, 50, 51]  ← 3 DOM nodes, always

With loop mode, it wraps at boundaries:

Current index: 0, loop: true
Visible: [9999, 0, 1]  ← seamless wrap

When you call goTo(5000) from index 0, it doesn't animate through 5,000 slides. It temporarily swaps the adjacent slide with the target, animates a single step, and resolves. One smooth transition — the virtualization handles the rest.

Signals, not React state

ReelKit implements its own reactive system:

Signal — writable observable value
ComputedSignal — lazy derived value (zero cost when unobserved)
batch() — groups multiple updates into a single notification pass

The React <Reel> component subscribes to these signals in effects and uses flushSync() on each animation frame to apply transforms synchronously — bypassing React's default batching. Your React tree doesn't re-render during swipes — transforms update at 60fps without touching component state.

When an animation completes, the index and transform value update in a single batch() call — observers never see an intermediate state. Navigation methods (next(), goTo()) return promises that resolve on completion, so you can chain transitions or await before taking the next action.

Touch-first gestures

The gesture controller detects the dominant axis from the initial touch vector and locks to it. It tracks per-frame delta, cumulative distance, and velocity. A fast swipe (> 1400 px/s) or drag past the threshold triggers a slide change with snap-back animation.

Packages

Package	What it does	Size (gzip)
`@reelkit/core`	Framework-agnostic engine	3.7 kB
`@reelkit/react`	React components + hooks	2.6 kB
`@reelkit/react-reel-player`	Full-screen video reel player	3.8 kB
`@reelkit/react-lightbox`	Image & video gallery lightbox	3.4 kB

@reelkit/core is the engine — all slider logic, gesture detection, keyboard/wheel controllers, and the signal system. Zero dependencies. Framework-agnostic. Vue bindings are in progress.

Everything in core is factory functions, not classes — createSliderController, createGestureController, createKeyboardController, createWheelController. Plain closures, no this binding issues, better tree-shaking.

@reelkit/react bridges the core to React. The <Reel> component creates a SliderController once via useState initializer and never recreates it. <ReelIndicator> renders Instagram-style scrollable dot indicators.

Reel Player

A ready-made TikTok/Instagram Reels overlay:

import { ReelPlayerOverlay } from '@reelkit/react-reel-player';
import '@reelkit/react-reel-player/styles.css';

<ReelPlayerOverlay
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  content={items}
  initialIndex={0}
/>

Videos autoplay when the slide becomes active, pause when swiped away. A shared video element is reused across slides for iOS sound continuity.

Lightbox

Full-screen image gallery with three transition modes (slide, fade, zoom-in), swipe-to-close, keyboard navigation, and fullscreen API:

import { LightboxOverlay } from '@reelkit/react-lightbox';
import '@reelkit/react-lightbox/styles.css';

<LightboxOverlay
  isOpen={index !== null}
  images={images}
  initialIndex={index ?? 0}
  onClose={() => setIndex(null)}
  transition="fade"
/>

Video support is opt-in and tree-shakeable — image-only usage pays zero extra cost.

Both packages expose render props for controls, navigation, and slide content — replace anything you need.

Links

If you're building a vertical feed, a reel player, or a gallery lightbox in React — give ReelKit a try. MIT licensed, open source.

Feedback, suggestions, and bug reports are welcome — open an issue or drop a comment below. And if ReelKit saved you some time, a GitHub star would mean a lot — it's a small thing, but it really helps the project get noticed.

DEV Community