Skip to main content

​
Overview

The File plugin allows you to upload and attach files to your document. It supports file type detection, size formatting, and configurable upload/delete handlers for integration with various storage providers (S3, Firebase, Cloudinary, etc.).

​
Installation

npm install @yoopta/file

​
Basic Usage

import { useMemo } from 'react';
import YooptaEditor, { createYooptaEditor } from '@yoopta/editor';
import File from '@yoopta/file';

const plugins = [File];

export default function Editor() {
  const editor = useMemo(() => createYooptaEditor({ plugins, marks: [] }), []);
  return <YooptaEditor editor={editor} onChange={() => {}} />;
}

​
Features

  • File Upload: Supports custom upload functions or endpoint-based uploads
  • File Delete: Optional delete handlers for removing files from storage
  • File Type Detection: Automatic detection of file types (PDF, document, image, video, etc.)
  • Size Formatting: Automatic formatting of file sizes (KB, MB, GB)
  • Progress Tracking: Upload progress monitoring
  • Shortcuts: Type file to insert

​
Configuration

​
With Custom Upload Function

import File from '@yoopta/file';

const filePlugin = File.extend({
  options: {
    upload: async (file, onProgress) => {
      // Upload to your storage (S3, Firebase, etc.)
      const formData = new FormData();
      formData.append('file', file);
      
      const response = await fetch('/api/upload', {
        method: 'POST',
        body: formData,
      });
      
      const data = await response.json();
      
      return {
        src: data.url,
        name: file.name,
        size: file.size,
        format: file.name.split('.').pop(),
      };
    },
    delete: async (element) => {
      // Delete from your storage
      await fetch(`/api/files/${element.props.id}`, {
        method: 'DELETE',
      });
    },
    accept: '.pdf,.doc,.docx,.xls,.xlsx,.txt',
    maxFileSize: 10 * 1024 * 1024, // 10MB
  },
});

const plugins = [filePlugin];

​
With Endpoint Configuration

import File from '@yoopta/file';

const filePlugin = File.extend({
  options: {
    upload: {
      endpoint: '/api/upload',
      method: 'POST',
      headers: {
        'Authorization': 'Bearer token',
      },
      fieldName: 'file',
      maxSize: 10 * 1024 * 1024,
      onProgress: (progress) => {
        console.log(`Upload progress: ${progress.percentage}%`);
      },
      onSuccess: (result) => {
        console.log('Upload successful:', result);
      },
      onError: (error) => {
        console.error('Upload failed:', error);
      },
    },
    delete: {
      endpoint: '/api/files',
      method: 'DELETE',
    },
  },
});

​
Options

​
upload
FileUploadOptions
Upload configuration - either a custom function or endpoint configuration
​
delete
FileDeleteOptions
Delete configuration - either a custom function or endpoint configuration
​
accept
string
File type filter (MIME types or extensions)
​
maxFileSize
number
Maximum file size in bytes
​
onError
(error: FileUploadError) => void
Global error handler

​
Element Props

​
file.props
object

​
Commands

​
insertFile

Insert a new File block. 
import File, { FileCommands } from '@yoopta/file';

FileCommands.insertFile(editor, {
  props: {
    src: 'https://example.com/document.pdf',
    name: 'document',
    size: 1024000,
    format: 'pdf',
  },
  at: 0,
  focus: true,
});
​
props
Partial<FileElementProps>
File element properties (src, name, size, format, id)
​
at
YooptaPathIndex
Index where to insert the block
​
focus
boolean
Whether to focus the new block after insert

​
updateFile

Update file properties. 
import { FileCommands } from '@yoopta/file';

FileCommands.updateFile(editor, blockId, {
  src: 'https://example.com/updated.pdf',
  name: 'updated',
});

​
deleteFile

Delete a file block. 
import { FileCommands } from '@yoopta/file';

FileCommands.deleteFile(editor, blockId);

​
buildFileElements

Build file element structure (used internally). 
import { FileCommands } from '@yoopta/file';

const fileElement = FileCommands.buildFileElements(editor, {
  props: { src: 'https://example.com/file.pdf' },
});

​
Hooks

​
useFileUpload

Hook for handling file uploads with state management. 
import { useFileUpload } from '@yoopta/file';

const { upload, loading, progress, error, result, cancel, reset } = useFileUpload({
  endpoint: '/api/upload',
  onSuccess: (result) => {
    console.log('Uploaded:', result);
  },
});

// Upload a file
const handleUpload = async (file) => {
  const result = await upload(file);
  console.log('File URL:', result.url);
};

​
useFileDelete

Hook for handling file deletions. 
import { useFileDelete } from '@yoopta/file';

const { deleteFile, loading, error } = useFileDelete({
  endpoint: '/api/files',
});

// Delete a file
const handleDelete = async (element) => {
  await deleteFile(element);
};

​
Utilities

​
File Type Detection

import {
  getFileType,
  getFileTypeConfig,
  getFileTypeLabel,
  getFileExtension,
  isFileType,
  FILE_TYPE_CONFIGS,
} from '@yoopta/file';

// Get file type from extension or MIME type
const type = getFileType('document.pdf'); // 'pdf'

// Get configuration for a file type
const config = getFileTypeConfig('pdf');
// { type: 'pdf', extensions: ['.pdf'], mimeTypes: ['application/pdf'], label: 'PDF' }

// Get label for display
const label = getFileTypeLabel('pdf'); // 'PDF'

// Extract extension from filename
const ext = getFileExtension('document.pdf'); // 'pdf'

// Check if file matches type
const isPdf = isFileType(file, 'pdf');

​
File Size Formatting

import { formatFileSize, parseFileSize } from '@yoopta/file';

// Format bytes to human-readable string
const formatted = formatFileSize(1536000); // '1.5 MB'

// Parse size string to bytes
const bytes = parseFileSize('1.5 MB'); // 1536000

​
Types

Supported file types:
  • pdf - PDF documents
  • document - Word, Pages, etc.
  • spreadsheet - Excel, Numbers, etc.
  • presentation - PowerPoint, Keynote, etc.
  • image - Images
  • video - Video files
  • audio - Audio files
  • archive - ZIP, RAR, etc.
  • code - Source code files
  • text - Plain text files
  • unknown - Unrecognized types

​
Parsers

​
HTML

  • Deserialize: <a> tags with download attribute or data-yoopta-file
  • Serialize: File block → <a> with download attribute, href, and metadata in data attributes

​
Markdown

  • Serialize: File → [filename.ext](url)

​
Email

  • Serialize: Table-based layout with file icon and download link styled for email clients

Build docs developers (and LLMs) love

Get started for freeTalk to us