---
title: "File Block — Attachments and Downloads"
description: "Attach arbitrary files with a download affordance, a file name, and size metadata stored on the block."
source: https://blokeditor.com/docs/file/
lastmod: 2026-09-07
---

Framework JavaScript

Block Tools File

# File block: attachments and downloads

An attachment card for any uploaded file. Shows a type icon, filename, human-readable size, a download action, and an optional caption. Files 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 itself (uploadByUrl). An optional MIME allowlist and max size can gate what is accepted.

### Import

TypeScript

```
import { File } from '@bloklabs/core/tools';
```

### Configuration

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `uploader` | `FileUploader` | `undefined` | Consumer-supplied uploader with optional `uploadByFile(file, ctx)` and `uploadByUrl(url, ctx)` methods, each resolving to `{ url, fileName?, size?, mimeType? }`. The `ctx.onProgress(percent)` callback reports upload progress. When omitted, files fall back to a blob URL or the pasted URL. |
| `endpoints` | `string | { byFile?: string; byUrl?: string }` | `undefined` | Upload endpoint(s) — Blok POSTs the upload itself (multipart/form-data for files, JSON `{ url }` for embedded URLs) and expects a `{ url, fileName?, size?, mimeType? }` body back. A string is used for both; an object targets each separately. An explicit `uploader` always takes precedence. |
| `field` | `string` | `"file"` | Form-data field name carrying the uploaded file. |
| `additionalRequestHeaders` | `Record<string, string>` | `undefined` | Extra headers merged into endpoint upload requests. |
| `types` | `string[]` | `undefined` | Optional MIME allowlist. When omitted, files of any type are accepted. |
| `sources` | `'upload' | 'url' | 'both'` | `'both'` | Restrict how a file may be added — file upload only, URL only, or both. |
| `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. |
| `captionPlaceholder` | `string` | `"Write a caption…"` | Placeholder text shown in the caption field. Defaults to the localized `tools.file.captionPlaceholder` string. |

### Save Data

TypeScript

```
interface FileData {
  url: string;             // File source URL — http(s) or blob:
  fileName?: string;       // Original filename, when known
  size?: number;           // File size in bytes; rendered human-readable
  mimeType?: string;       // MIME type; used to pick the type icon
  caption?: string;        // Plain-text caption
  captionVisible?: boolean; // Whether the caption row is shown. Opt-in: when omitted it
                            // resolves to true only if `caption` already has text
                            // (unlike Image/Video, which default to true).
}
```

JSON

```
{
  "id": "fil001",
  "type": "file",
  "data": {
    "url": "https://example.com/files/report.pdf",
    "fileName": "report.pdf",
    "size": 184320,
    "mimeType": "application/pdf"
  }
}
```

### Usage Example

TypeScript

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

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