solidjs-community · davedbase · May 24, 2026 · May 24, 2026 · May 24, 2026 · May 25, 2026
diff --git a/.changeset/video-initial.md b/.changeset/video-initial.md
@@ -0,0 +1,27 @@
+---
+"@solid-primitives/video": minor
+---
+
+New package: `@solid-primitives/video`
+
+Layered primitives for managing HTML video playback, built for Solid 2.0 (beta.14).
+
+### `makeVideo`
+
+Non-reactive base. Creates an `HTMLVideoElement` with optional event handlers and initial configuration (`autoPlay`, `loop`, `muted`, `preload`). Returns a `[player, cleanup]` tuple. No Solid owner required.
+
+### `makeVideoPlayer`
+
+Wraps `makeVideo` with imperative controls: `play`, `pause`, `seek`, `setVolume`, `setMuted`, `setPlaybackRate`, and `setLoop`.
+
+### `createVideo`
+
+Reactive primitive covering essential playback state: `playing`/`setPlaying`, `currentTime`/`seek`, `ended`, `seeking`, `error` (`MediaError | null`), and `duration` (throws `NotReadyError` until metadata loads — integrates with `<Loading>`). Accepts a static or reactive `VideoSource` and optional `VideoOptions`.
+
+### `createVideoPlayer`
+
+Extends `createVideo` with the full control surface: `volume`/`setVolume`, `muted`/`setMuted`, `playbackRate`/`setPlaybackRate`, `loop`/`setLoop`, `buffered`, `readyState`, `videoWidth`, and `videoHeight`. Accepts `VideoControlsOptions` which adds `volume` and `playbackRate` initial values to `VideoOptions`.
+
+### Design notes
+
+`createVideo` and `createVideoPlayer` are composable — `createVideoPlayer` calls `createVideo` internally and layers additional `createEventListenerMap` bindings on the same player element. Choose the primitive that matches your needs; the non-reactive `make*` layer remains available when no Solid owner is present.
diff --git a/.storybook/main.ts b/.storybook/main.ts
@@ -6,6 +6,7 @@ const config: StorybookConfig = {
   staticDirs: [
     { from: "../packages/audio/stories/assets", to: "/audio" },
     { from: "../assets/img", to: "/img" },
+    { from: "../assets/video", to: "/video" },
     { from: "../node_modules/geist/dist/fonts", to: "/geist-fonts" },
   ],
   addons: ["@storybook/addon-docs"],

diff --git a/assets/video/big_buck_bunny_sall.mp4 b/assets/video/big_buck_bunny_sall.mp4
diff --git a/packages/video/LICENSE b/packages/video/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Solid Primitives Working Group
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/packages/video/README.md b/packages/video/README.md
@@ -0,0 +1,178 @@
+<p>
+  <img width="100%" src="https://assets.solidjs.com/banner?type=Primitives&background=tiles&project=Video" alt="Solid Primitives Video">
+</p>
+
+# @solid-primitives/video
+
+[![size](https://img.shields.io/bundlephobia/minzip/@solid-primitives/video?style=for-the-badge&label=size)](https://bundlephobia.com/package/@solid-primitives/video)
+[![version](https://img.shields.io/npm/v/@solid-primitives/video?style=for-the-badge)](https://www.npmjs.com/package/@solid-primitives/video)
+[![stage](https://img.shields.io/endpoint?style=for-the-badge&url=https%3A%2F%2Fraw.githubusercontent.com%2Fsolidjs-community%2Fsolid-primitives%2Fmain%2Fassets%2Fbadges%2Fstage-0.json)](https://github.com/solidjs-community/solid-primitives#contribution-process)
+
+Layered primitives for managing HTML video playback. The `make*` variants are non-reactive and require no Solid owner. The `create*` variants integrate with Solid's reactive system — `createVideo` covers essential playback state, and `createVideoPlayer` extends it with the full control surface.
+
+## Installation
+
+```bash
+npm install @solid-primitives/video
+# or
+pnpm add @solid-primitives/video
+```
+
+## How to use it
+
+### `makeVideo`
+
+Creates a raw `HTMLVideoElement` with optional event handlers and initial configuration. No Solid owner required.
+
+```ts
+const [player, cleanup] = makeVideo('clip.mp4', {}, { muted: true, loop: true });
+cleanup();
+```
+
+```ts
+function makeVideo(
+  src: VideoSource | HTMLVideoElement,
+  handlers?: VideoEventHandlers,
+  options?: VideoOptions,
+): [player: HTMLVideoElement, cleanup: VoidFunction];
+```
+
+### `makeVideoPlayer`
+
+Wraps `makeVideo` with imperative playback controls. No Solid owner required.
+
+```ts
+const [{ play, pause, seek, setVolume, setMuted, setPlaybackRate, setLoop }, cleanup] =
+  makeVideoPlayer('clip.mp4');
+
+await play();
+seek(30);
+setPlaybackRate(1.5);
+setLoop(true);
+cleanup();
+```
+
+```ts
+function makeVideoPlayer(
+  src: VideoSource | HTMLVideoElement,
+  handlers?: VideoEventHandlers,
+  options?: VideoOptions,
+): [controls: VideoControls, cleanup: VoidFunction];
+```
+
+### `createVideo`
+
+Essential reactive playback state: `playing`, `currentTime`, `ended`, `seeking`, `error`, and an async `duration` that suspends until metadata is loaded.
+
+```ts
+const video = createVideo('clip.mp4');
+// or with a reactive source:
+const video = createVideo(() => selectedUrl());
+
+video.playing()         // boolean — true while actively playing
+video.setPlaying(true)  // plays
+video.currentTime()     // seconds
+video.seek(30)
+video.ended()           // boolean
+video.seeking()         // boolean — true while scrubbing
+video.error()           // MediaError | null
+```
+
+The `duration` accessor throws `NotReadyError` until video metadata has loaded, integrating with Solid 2.0's `<Loading>` boundary:
+
+```tsx
+<Loading fallback="Loading…">
+  <span>{video.duration()}s</span>
+</Loading>
+```
+
+```ts
+function createVideo(
+  src: VideoSource | Accessor<VideoSource>,
+  options?: VideoOptions,
+): VideoReturn;
+```
+
+### `createVideoPlayer`
+
+Extends `createVideo` with the full control surface: volume, muted, playback rate, loop, buffering state, and dimensions. Accepts all `VideoOptions` plus `volume` and `playbackRate` initial values.
+
+```ts
+const video = createVideoPlayer('clip.mp4', {
+  muted: true,
+  volume: 0.8,
+  playbackRate: 1,
+});
+
+// All fields from createVideo, plus:
+video.volume()              // 0–1
+video.setVolume(0.5)
+video.muted()               // boolean
+video.setMuted(true)
+video.playbackRate()        // number
+video.setPlaybackRate(1.5)
+video.loop()                // boolean
+video.setLoop(true)
+video.buffered()            // TimeRanges | undefined
+video.readyState()          // 0–4
+video.videoWidth()          // intrinsic pixel width
+video.videoHeight()         // intrinsic pixel height
+```
+
+> **Fullscreen** is intentionally omitted — use the dedicated `@solid-primitives/fullscreen` primitive to manage fullscreen state and attach it to `video.player`.
+
+```ts
+function createVideoPlayer(
+  src: VideoSource | Accessor<VideoSource>,
+  options?: VideoControlsOptions,
+): VideoControlsReturn;
+```
+
+## Types
+
+```ts
+type VideoSource = string | undefined | MediaProvider;
+
+type VideoOptions = {
+  autoPlay?: boolean;
+  loop?: boolean;
+  muted?: boolean;
+  preload?: "" | "none" | "metadata" | "auto";
+};
+
+type VideoControlsOptions = VideoOptions & {
+  volume?: number;
+  playbackRate?: number;
+};
+
+type VideoReturn = {
+  player: HTMLVideoElement;
+  playing: Accessor<boolean>;
+  setPlaying: (v: boolean) => void;
+  currentTime: Accessor<number>;
+  seek: (time: number) => void;
+  ended: Accessor<boolean>;
+  seeking: Accessor<boolean>;
+  error: Accessor<MediaError | null>;
+  duration: Accessor<number>; // throws NotReadyError until loaded
+};
+
+type VideoControlsReturn = VideoReturn & {
+  volume: Accessor<number>;
+  setVolume: (v: number) => void;
+  muted: Accessor<boolean>;
+  setMuted: (v: boolean) => void;
+  playbackRate: Accessor<number>;
+  setPlaybackRate: (rate: number) => void;
+  loop: Accessor<boolean>;
+  setLoop: (v: boolean) => void;
+  buffered: Accessor<TimeRanges | undefined>;
+  readyState: Accessor<number>;
+  videoWidth: Accessor<number>;
+  videoHeight: Accessor<number>;
+};
+```
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md)
diff --git a/packages/video/dev/index.tsx b/packages/video/dev/index.tsx
@@ -0,0 +1,78 @@
+import { type Component, createSignal } from "solid-js";
+import { createVideoPlayer } from "../src/index.js";
+
+const DEMO_URL =
+  "https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4";
+
+const App: Component = () => {
+  const [src, setSrc] = createSignal(DEMO_URL);
+  const video = createVideoPlayer(src);
+
+  return (
+    <div class="box-border flex min-h-screen w-full flex-col items-center justify-center space-y-4 bg-gray-800 p-24 text-white">
+      <div class="wrapper-v space-y-4">
+        <h4>Video Primitive Demo</h4>
+        <video
+          ref={el => {
+            // sync the reactive player into the DOM element
+            (video as any).player = el;
+          }}
+          src={src()}
+          style={{ width: "640px", "max-width": "100%" }}
+        />
+
+        <div class="flex gap-2">
+          <button class="btn" onClick={() => video.setPlaying(!video.playing())}>
+            {video.playing() ? "Pause" : "Play"}
+          </button>
+          <button class="btn" onClick={() => video.setMuted(!video.muted())}>
+            {video.muted() ? "Unmute" : "Mute"}
+          </button>
+
+        </div>
+
+        <div class="space-y-1 text-sm">
+          <p>
+            Time: {video.currentTime().toFixed(1)}s — Ended: {String(video.ended())}
+          </p>
+          <p>
+            Volume: {video.volume().toFixed(2)} — Muted: {String(video.muted())}
+          </p>
+          <p>
+            Playback rate: {video.playbackRate()}x — Ready state: {video.readyState()}
+          </p>
+          <p>
+            Dimensions: {video.videoWidth()} × {video.videoHeight()}
+          </p>
+        </div>
+
+        <div class="flex items-center gap-2">
+          <label>Volume</label>
+          <input
+            type="range"
+            min="0"
+            max="1"
+            step="0.05"
+            value={video.volume()}
+            onInput={e => video.setVolume(Number((e.target as HTMLInputElement).value))}
+          />
+        </div>
+
+        <div class="flex items-center gap-2">
+          <label>Speed</label>
+          <select
+            value={video.playbackRate()}
+            onChange={e => video.setPlaybackRate(Number((e.target as HTMLSelectElement).value))}
+          >
+            <option value="0.5">0.5×</option>
+            <option value="1">1×</option>
+            <option value="1.5">1.5×</option>
+            <option value="2">2×</option>
+          </select>
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export default App;
diff --git a/packages/video/package.json b/packages/video/package.json
@@ -0,0 +1,69 @@
+{
+  "name": "@solid-primitives/video",
+  "version": "0.0.100",
+  "description": "Primitives to manage HTML video playback.",
+  "author": "David Di Biase <dave@solidjs.com>",
+  "contributors": [],
+  "license": "MIT",
+  "homepage": "https://primitives.solidjs.community/package/video",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/solidjs-community/solid-primitives.git"
+  },
+  "bugs": {
+    "url": "https://github.com/solidjs-community/solid-primitives/issues"
+  },
+  "primitive": {
+    "name": "video",
+    "stage": 0,
+    "list": [
+      "makeVideo",
+      "makeVideoPlayer",
+      "createVideo",
+      "createVideoPlayer"
+    ],
+    "category": "Display & Media"
+  },
+  "keywords": [
+    "solid",
+    "primitives",
+    "video",
+    "media"
+  ],
+  "private": false,
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "browser": {},
+  "exports": {
+    "import": {
+      "@solid-primitives/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "typesVersions": {},
+  "scripts": {
+    "dev": "node --import=@nothing-but/node-resolve-ts --experimental-transform-types ../../scripts/dev.ts",
+    "build": "node --import=@nothing-but/node-resolve-ts --experimental-transform-types ../../scripts/build.ts",
+    "vitest": "vitest -c ../../configs/vitest.config.ts",
+    "test": "pnpm run vitest",
+    "test:ssr": "pnpm run vitest --mode ssr"
+  },
+  "dependencies": {
+    "@solid-primitives/event-listener": "workspace:^",
+    "@solid-primitives/utils": "workspace:^"
+  },
+  "devDependencies": {
+    "@solidjs/web": "2.0.0-beta.14",
+    "solid-js": "2.0.0-beta.14"
+  },
+  "peerDependencies": {
+    "@solidjs/web": "^2.0.0-beta.14",
+    "solid-js": "^2.0.0-beta.14"
+  }
+}