---
title: "Image Block — Upload, Paste, Resize, Compress"
description: "Upload, paste, or link images, with resizing, captions, client-side compression, and an enforced size limit."
source: https://blokeditor.com/docs/image/
lastmod: 2026-09-07
---

Framework JavaScript

Block Tools Image

# 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'`), `fallbackFormat` (format to try when the browser cannot encode `format`, before falling back to the source format — e.g. `{ format: 'avif', fallbackFormat: 'webp' }` uploads AVIF where the browser can produce it and WebP everywhere else), `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 };
          },
        },
      },
    },
  },
});
```