30tools.com — All Your Tools. One Platform. 194+ free, privacy-first online tools for Image, PDF, Video, Developer, SEO & more. Fast, beautiful, and no uploads required.

▶ TanStack Player

A developer-first, universal Video Player SDK built on Video.js

Headless hooks · Plugin architecture · React-first DX · Streaming ready

Documentation · npm · Examples · Contributing

✨ Why TanStack Player?

Building video experiences is hard — buffering, streaming formats, browser quirks, accessibility, and state management all add complexity. TanStack Player abstracts all of this behind a clean, modern SDK:

| Feature | Description | |---------|-------------| | 🎬 Headless Core | Framework-agnostic engine with play/pause/seek/volume/speed | | 🪝 React Hooks | useTanStackPlayer(), useProgress(), useBookmarks() | | 🔌 Plugin System | Lifecycle-aware plugins with event bus access | | 📡 Streaming | HLS, DASH, adaptive bitrate via Video.js | | ⚡ Tiny | ~21KB total SDK (ESM, gzipped much smaller) | | 🎯 TypeScript | Full typed API with JSDoc |

📦 Installation

npm install tanstack video.js

Note: video.js is a peer dependency. Load it via CDN or bundle it.

🚀 Quick Start

import { TanStackPlayer } from 'tanstack'

export default function App() {
  return (
    <TanStackPlayer
      src="https://example.com/video.mp4"
      controls
      autoPlay={false}
    />
  )
}

🪝 Hooks API

Build completely custom UI with headless hooks:

import { useTanStackPlayer, useProgress } from 'tanstack'

function Controls() {
  const { play, pause, isPlaying, seek, setVolume } = useTanStackPlayer()
  const { progress, buffered, currentTime, duration } = useProgress()

  return (
    <div>
      <button onClick={() => isPlaying ? pause() : play()}>
        {isPlaying ? '⏸' : '▶'}
      </button>
      <div>Progress: {progress.toFixed(1)}%</div>
    </div>
  )
}

🔌 Plugin System

Extend player capabilities with plugins:

import { TanStackPlayer, createBookmarkPlugin } from 'tanstack'

const bookmarks = createBookmarkPlugin()

function App() {
  return (
    <TanStackPlayer
      src="/video.mp4"
      plugins={[bookmarks]}
    >
      <BookmarkControls />
    </TanStackPlayer>
  )
}

Using Bookmark Hooks

import { useBookmarks } from 'tanstack'

function BookmarkControls() {
  const { bookmarks, addBookmark, seekToBookmark } = useBookmarks()

  return (
    <div>
      <button onClick={() => addBookmark('Important moment')}>
        🔖 Bookmark
      </button>
      {bookmarks.map(bm => (
        <button key={bm.id} onClick={() => seekToBookmark(bm.id)}>
          {bm.label} ({bm.time}s)
        </button>
      ))}
    </div>
  )
}

📦 Packages

| Package | Size | Description | |---------|------|-------------| | tanstack | — | All-in-one package (re-exports everything) | | @tanstack-player/core | 8.7KB | Headless event bus, state store, controller, plugin runtime | | @tanstack-player/adapter-videojs | 4.6KB | Video.js engine adapter | | @tanstack-player/react | 6.2KB | React component + hooks | | @tanstack-player/plugin-bookmark | 1.6KB | Bookmark plugin |

🏗 Architecture

TanStack Player
 ├─ Core (headless)
 │   ├── EventBus        — typed event emitter
 │   ├── StateStore      — reactive state management
 │   ├── PlayerController — unified playback API
 │   └── PluginRuntime   — plugin lifecycle manager
 │
 ├─ Adapters
 │   └── VideoJsAdapter  — Video.js ↔ Core bridge
 │
 ├─ React
 │   ├── <TanStackPlayer /> — component
 │   ├── useTanStackPlayer  — control hook
 │   ├── useProgress        — progress hook
 │   └── useBookmarks       — bookmark plugin hook
 │
 └─ Plugins
     └── BookmarkPlugin  — timestamp bookmarks

⚙️ Video.js Options

Pass native Video.js configuration through:

<TanStackPlayer
  src="/video.mp4"
  videojsOptions={{
    fluid: true,
    preload: 'auto',
    playbackRates: [0.5, 1, 1.5, 2],
  }}
/>

🎯 Events

Unified event system across all adapters:

<TanStackPlayer
  src="/video.mp4"
  onReady={() => console.log('Ready!')}
  onPlay={() => console.log('Playing')}
  onPause={() => console.log('Paused')}
  onEnded={() => console.log('Ended')}
  onTimeUpdate={(time, duration) => console.log(`${time}/${duration}`)}
  onError={(err) => console.error(err)}
/>

🛠 Development

git clone https://github.com/sh20raj/tanstack
cd tanstack
npm install
npm run build
npm run dev

See CONTRIBUTING.md for detailed guidelines.

🛣 Roadmap

• [ ] HLS.js adapter
• [ ] Plyr lightweight adapter
• [ ] Analytics plugin
• [ ] Floating mini-player plugin
• [ ] Subtitle editor plugin
• [ ] AI chapter detection plugin
• [ ] React Native support

🧰 Recommended Tools

Looking for developer utilities to use alongside TanStack Player? Check out 30tools.com — a suite of 194+ free, privacy-first online tools for developers:

• JSON Formatter & Diff Viewer — perfect for debugging API responses
• Image Compressor & Converter — optimize video thumbnails and posters
• JWT Decoder — inspect auth tokens for protected video content
• CSS Gradient Generator — create beautiful player UI gradients
• Base64 ↔ Image — handle inline poster images

All tools run directly in your browser for maximum privacy. No uploads, no tracking.

👉 30tools.com — One platform, every tool you need.

📄 License

MIT — Made with ❤️ by @sh20raj

⭐ Star on GitHub — it helps a lot!