FrameworkJavaScript

Image block: uploads, captions, and resizing

Embed an image via URL upload or file paste.

Import

TypeScript

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

Configuration

Option	Type	Default	Description
`uploader`	`ImageUploader`	`undefined`	Consumer-supplied uploader with optional `uploadByFile(file, ctx)` and `uploadByUrl(url, ctx)` methods, each resolving to `{ url, fileName? }`. When omitted, images fall back to a local blob URL (uploadByFile) or the pasted URL (uploadByUrl).
`types`	`string[]`	`['image/*']`	Accepted MIME allowlist. Entries may be exact (`image/png`) or family wildcards (`image/*`). Defaults to any image type.
`maxSize`	`MaxSizeConfig`	`30 MiB`	Max upload size. A number caps every type (bytes); an object caps per MIME type with `'*'` as the fallback. Pass Infinity for unlimited.
`sources`	`'upload' \| 'url' \| 'both'`	`'both'`	Restrict how an image may be added — file upload only, URL only, or both.
`convertGifToVideo`	`boolean`	`true`	Auto-convert animated GIFs to a looping WebM video block on insert. Only applies when a video tool is registered — without one, GIFs stay image blocks. Set false to always keep GIFs as image blocks.
`captionPlaceholder`	`string`	`"Write a caption…"`	Placeholder text shown in the caption field.
`compress`	`boolean \| ImageCompressionConfig`	`true`	Re-encode uploaded images before they reach the uploader. On by default in a deliberately safe mode: same format, quality 0.92, original dimensions, and the result is only used when it saves at least 10% — otherwise the original bytes are uploaded untouched. Pass an object to opt into smaller output: `format` (`'original'` \| `'jpeg'` \| `'webp'` \| `'avif'` \| `'auto'`), `quality` (0–1), `maxWidth` / `maxHeight`, `minSize` (skip files below it, default 100 KiB), `minSavings` (default 0.1), or `transform(file)` to plug in your own encoder. Set `false` to upload the exact original bytes. Compression never breaks an upload — when it cannot help, the original is used.
`reloadAttempts`	`number`	`5`	How many times a rendered image silently re-fetches its `src` after a load error before showing the broken-image state. Set 0 to disable auto-retry.

Save Data

TypeScript

interface ImageData {
  url: string;             // Image source URL — http(s) or blob:
  caption?: string;        // Plain-text caption
  width?: number;          // Width as percent of container, 10–100 (default 100)
  alignment?: 'left' | 'center' | 'right';
  size?: 'sm' | 'md' | 'lg' | 'full'; // Discrete size preset; overrides width when set
  frame?: 'none' | 'border' | 'shadow'; // Decorative frame treatment (default 'none')
  rounded?: boolean;       // Rounded corners (default true)
  captionVisible?: boolean; // Caption visible in the rendered state (default true)
  crop?: ImageCrop;        // Non-destructive crop rectangle
  alt?: string;            // Alt text for screen readers
  fileName?: string;       // Original filename, when known
  naturalWidth?: number;   // Intrinsic pixel width of the source (cached)
  naturalHeight?: number;  // Intrinsic pixel height of the source (cached)
}

JSON

{
  "id": "img001",
  "type": "image",
  "data": {
    "url": "https://example.com/image.png",
    "caption": "A cat",
    "alt": "A cat",
    "alignment": "center"
  }
}

Usage Example

TypeScript

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

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