FrameworkJavaScript

File block: attachments and downloads

An attachment card for any uploaded file. It shows a type icon, filename, human-readable size, a download action, and an optional caption.

Files are sent through an uploader that you supply. When there is none, the tool falls back to a local blob URL (uploadByFile) or to 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`	An uploader you supply. It has two optional methods, `uploadByFile(file, ctx)` and `uploadByUrl(url, ctx)`, and each one resolves to `{ url, fileName?, size?, mimeType? }`. The `ctx.onProgress(percent)` callback reports upload progress. When you omit the uploader, files fall back to a blob URL or the pasted URL.
`endpoints`	`string \| { byFile?: string; byUrl?: string }`	`undefined`	Upload endpoint or endpoints. Blok POSTs the upload itself: multipart/form-data for files, JSON `{ url }` for embedded URLs. It 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, in bytes. An object caps each MIME type, and `'*'` is the fallback. Pass Infinity for unlimited.
`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`.
`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 };
          },
        },
      },
    },
  },
});