FrameworkJavaScript

Video block: uploads and embedded players

A video player block. It renders an uploaded or linked video with a custom control bar.

The bar has play/pause, a scrubber with buffered range and hover preview, volume, playback speed, loop, picture-in-picture, theater and fullscreen modes. It can also show a caption and an ambient glow behind the player.

Videos are sent through a consumer-supplied uploader. When none is provided, the tool falls back to a local blob URL (uploadByFile) or the pasted URL (uploadByUrl). An optional MIME allowlist and max size gate what is accepted.

Import

TypeScript

import { Video } from '@bloklabs/core/tools';

Configuration

Option	Type	Default	Description
`uploader`	`VideoUploader`	`undefined`	Consumer-supplied uploader with optional `uploadByFile(file, ctx)` (resolving to `{ url, fileName? }`) and `uploadByUrl(url, ctx)` (resolving to `{ url }`) methods. The `ctx.onProgress(percent)` callback reports upload progress. When omitted, videos fall back to a blob URL or the entered URL. That URL then has to be a direct media file (`.mp4`, `.webm`, `.ogg`, `.mov`, `.m4v`), because it becomes the `<video src>` verbatim. Provide `uploadByUrl` to accept any URL and resolve it yourself.
`types`	`string[]`	`['video/*']`	Accepted MIME allowlist for uploads. Entries may be exact (`video/mp4`) or family wildcards (`video/*`). Defaults to any video type.
`maxSize`	`MaxSizeConfig`	`100 MiB`	Max upload size. A number caps every type, in bytes. An object caps each MIME type, with `'*'` as the fallback.
`onUploadError`	`UploadErrorHandler`	`undefined`	Called when an upload fails. It receives `{ code, tool, message, file?, url?, size?, maxSize?, cause }`. Return nothing: the block shows its own message. Return a string: the block shows it instead. Return `false`: the block goes back to its empty state with no error, so you can show a toast. A rejection from your own uploader arrives as `UPLOAD_FAILED`. The original error is in `cause`.
`sources`	`'upload' \| 'url' \| 'both'`	`'both'`	Restrict how the media may be added: file upload only, URL only, or both.
`captionPlaceholder`	`string`	`"Write a caption…"`	Placeholder text shown in the caption field.
`glow`	`'more' \| 'less' \| 'minimal' \| 'none'`	`'minimal'`	Ambient glow intensity rendered behind every player.

Save Data

TypeScript

interface VideoData {
  url: string;             // Video source URL — http(s) or blob:
  caption?: string;        // Plain-text caption
  captionVisible?: boolean; // Caption visible in the rendered state (default true)
  width?: number;          // Width as percent of the editor container, 10–100 (resize handle, default 100)
  alignment?: 'left' | 'center' | 'right';
  autoplay?: boolean;      // Autoplay on render
  loop?: boolean;          // Loop playback
  hideControls?: boolean;  // Render a control-free player
  fileName?: string;       // Original filename, when known
  mimeType?: string;       // MIME type
  aspectRatio?: string;    // e.g. "16 / 9", used to reserve layout space
  variants?: { url: string; mimeType: string }[]; // Other formats, best first
}

JSON

{
  "id": "vid001",
  "type": "video",
  "data": {
    "url": "https://example.com/media/clip.mp4",
    "fileName": "clip.mp4",
    "mimeType": "video/mp4",
    "alignment": "center"
  }
}

Usage Example

TypeScript

import { Blok } from '@bloklabs/core';
import { Video } from '@bloklabs/core/tools';

const editor = new Blok({
  holder: 'editor',
  tools: {
    video: {
      class: Video,
      config: {
        uploader: {
          async uploadByFile(file) {
            const url = await myUpload(file);
            return { url, fileName: file.name };
          },
        },
      },
    },
  },
});