npm package: @reelkit/react
Description: React components and hooks for building TikTok/Instagram Reels-style sliders
Latest version: 0.3.0

# @reelkit/react

<p>
  <a href="https://www.npmjs.com/package/@reelkit/react"><img src="https://img.shields.io/npm/v/@reelkit/react?color=6366f1&label=npm" alt="npm" /></a>
  <img src="https://img.shields.io/badge/gzip-3.9%20kB-6366f1" alt="Bundle size" />
  <img src="https://img.shields.io/badge/coverage-96%25-brightgreen" alt="Coverage" />
  <a href="https://github.com/KonstantinKai/reelkit"><img src="https://img.shields.io/github/stars/KonstantinKai/reelkit?style=social" alt="Star on GitHub" /></a>
</p>

React bindings for `@reelkit/core`. Drop in a `<Reel>` component, give it a slide count and a render function — it handles virtualization, gestures, and keyboard/wheel input. ~3.9 kB gzip.

## Installation

```bash
npm install @reelkit/react
```

## Quick Start

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

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

  return (
    <Reel
      count={100}
      direction="vertical"
      afterChange={setIndex}
      itemBuilder={(i) => (
        <div style={{ width: '100%', height: '100%' }}>Slide {i + 1}</div>
      )}
    >
      <ReelIndicator count={100} active={index} />
    </Reel>
  );
}
```

## Features

- `<Reel>` — virtualized slider, keeps only 3 slides in the DOM
- `<ReelIndicator>` — dot indicators that auto-connect to the parent `<Reel>` via context
- Measures its own size via ResizeObserver — no width/height props needed
- Swipe with momentum and snap, keyboard arrows, mouse wheel
- Loop mode for infinite circular scrolling
- SSR compatible (Next.js, Remix, etc.)
- Typed with TypeScript, no `@types` package needed

## API

### Reel Props

| Prop                  | Type                         | Default      | Description                   |
| --------------------- | ---------------------------- | ------------ | ----------------------------- |
| `count`               | `number`                     | required     | Number of slides              |
| `itemBuilder`         | `(index) => ReactElement`    | required     | Render function for slides    |
| `direction`           | `'horizontal' \| 'vertical'` | `'vertical'` | Slide direction               |
| `initialIndex`        | `number`                     | `0`          | Starting slide index          |
| `loop`                | `boolean`                    | `false`      | Enable infinite loop          |
| `swipeDistanceFactor` | `number`                     | `0.12`       | Swipe threshold (0-1)         |
| `transitionDuration`  | `number`                     | `300`        | Animation duration in ms      |
| `enableNavKeys`       | `boolean`                    | `true`       | Enable keyboard navigation    |
| `enableWheel`         | `boolean`                    | `false`      | Enable mouse wheel navigation |
| `wheelDebounceMs`     | `number`                     | `200`        | Wheel debounce duration       |
| `apiRef`              | `ref`                        | -            | Ref to access public API      |
| `afterChange`         | `(index) => void`            | -            | Callback after slide change   |
| `beforeChange`        | `(index, nextIndex) => void` | -            | Callback before slide change  |

### ReelIndicator Props

| Prop         | Type              | Default  | Description                  |
| ------------ | ----------------- | -------- | ---------------------------- |
| `count`      | `number`          | required | Total number of slides       |
| `active`     | `number`          | required | Currently active slide index |
| `radius`     | `number`          | `3`      | Dot radius in pixels         |
| `visible`    | `number`          | `3`      | Number of visible dots       |
| `onDotClick` | `(index) => void` | -        | Callback when dot is clicked |

## Documentation

API reference, demos, and guides at **[reelkit.dev](https://reelkit.dev)**.

## Support

If ReelKit saved you some time, a star on GitHub would mean a lot — it's a small thing, but it really helps the project get noticed.

[![Star on GitHub](https://img.shields.io/github/stars/KonstantinKai/reelkit?style=social)](https://github.com/KonstantinKai/reelkit)

## License

[MIT](LICENSE)