Media

Embed medias like videos or tweets into your document.

Image Element Video Element Audio Element File Element Media Embed Element Media Popover Media Placeholder Element Media Upload Toast Media Toolbar Button Upload Media Toolbar

components/demo.tsx

'use client';

import * as React from 'react';

import { Plate } from '@udecode/plate/react';

import { editorPlugins } from '@/components/editor/plugins/editor-plugins';
import { useCreateEditor } from '@/components/editor/use-create-editor';
import { Editor, EditorContainer } from '@/components/ui/editor';

import { DEMO_VALUES } from './values/demo-values';

export default function Demo({ id }: { id: string }) {
  const editor = useCreateEditor({
    plugins: [...editorPlugins],
    value: DEMO_VALUES[id],
  });

  return (
    <Plate editor={editor}>
      <EditorContainer variant="demo">
        <Editor />
      </EditorContainer>
    </Plate>
  );
}

Features

Media Features

Editable captions
Resizable elements

Media Support

File types:
- Image
- Video
- Audio
- Others (PDF, Word, etc.)
Video providers:
- Local video files
- YouTube, Vimeo, Dailymotion, Youku, Coub
Embed providers:
- Tweets

Upload

Multiple upload methods:
- Toolbar button with file picker
- Drag and drop from file system
- Paste from clipboard (images)
- URL embedding for external media
Upload experience:
- Real-time progress tracking
- Preview during upload
- Automatically converts the placeholder to the appropriate media element (image, video, audio, file) once the upload or embed is submitted
- Error handling
- File size validation
- Type validation

Installation

pnpm add @udecode/plate-media

Usage

import {
  AudioPlugin,
  FilePlugin,
  ImagePlugin,
  MediaEmbedPlugin,
  PlaceholderPlugin,
  VideoPlugin,
} from '@udecode/plate-media/react';
import { SelectOnBackspacePlugin } from '@udecode/plate-select';

const plugins = [
  // ...otherPlugins,
  ImagePlugin,
  VideoPlugin,
  AudioPlugin,
  FilePlugin,
  MediaEmbedPlugin,
  SelectOnBackspacePlugin.configure({
    options: {
      query: {
        allow: [ImagePlugin.key, VideoPlugin.key, AudioPlugin.key, FilePlugin.key, MediaEmbedPlugin.key],
      },
    },
  }),
  PlaceholderPlugin.configure({
    options: { disableEmptyPlaceholder: true },
    render: { afterEditable: MediaUploadToast },
  }),
];

const components = {
  // ...otherComponents,
  [ImagePlugin.key]: ImageElement,
  [VideoPlugin.key]: VideoElement,
  [AudioPlugin.key]: AudioElement,
  [FilePlugin.key]: FileElement,
  [MediaEmbedPlugin.key]: MediaEmbedElement,
  [PlaceholderPlugin.key]: MediaPlaceholderElement,
};

Caption

To enable media captions, use the Caption Plugin.

Upload

There are two ways to implement file uploads in your editor:

Using our UploadThing implementation
Creating a custom implementation with your preferred upload solution

UploadThing

Add MediaPlaceholderElement component
Add API routes for UploadThing:

npx shadcn@canary add https://platejs.org/r/api-uploadthing

Get your secret key from UploadThing for free
Add your UploadThing secret key to .env:

.env

UPLOADTHING_TOKEN=xxx

Custom Implementation

For custom implementations, you'll need to create an upload hook that matches our interface. This can work with any upload backend (AWS S3, UploadThing, Cloudinary, Firebase Storage, etc.).

The upload hook should implement this interface:

interface UseUploadFileProps {
  onUploadComplete?: (file: UploadedFile) => void;
  onUploadError?: (error: unknown) => void;
  headers?: Record<string, string>;
  onUploadBegin?: (fileName: string) => void;
  onUploadProgress?: (progress: { progress: number }) => void;
  skipPolling?: boolean;
}
 
interface UploadedFile {
  key: string;    // Unique identifier
  url: string;    // Public URL of the uploaded file
  name: string;   // Original filename
  size: number;   // File size in bytes
  type: string;   // MIME type
}

Example implementation with S3 presigned URLs:

export function useUploadFile({ 
  onUploadComplete, 
  onUploadError, 
  onUploadProgress 
}: UseUploadFileProps = {}) {
  const [uploadedFile, setUploadedFile] = useState<UploadedFile>();
  const [uploadingFile, setUploadingFile] = useState<File>();
  const [progress, setProgress] = useState(0);
  const [isUploading, setIsUploading] = useState(false);
 
  async function uploadFile(file: File) {
    setIsUploading(true);
    setUploadingFile(file);
 
    try {
      // Get presigned URL and final URL from your backend
      const { presignedUrl, fileUrl, fileKey } = await fetch('/api/upload', {
        method: 'POST',
        body: JSON.stringify({
          filename: file.name,
          contentType: file.type,
        }),
      }).then(r => r.json());
 
      // Upload to S3 using presigned URL
      await axios.put(presignedUrl, file, {
        headers: { 'Content-Type': file.type },
        onUploadProgress: (progressEvent) => {
          const progress = (progressEvent.loaded / progressEvent.total) * 100;
          setProgress(progress);
          onUploadProgress?.({ progress });
        },
      });
 
      const uploadedFile = {
        key: fileKey,
        url: fileUrl,
        name: file.name,
        size: file.size,
        type: file.type,
      };
 
      setUploadedFile(uploadedFile);
      onUploadComplete?.(uploadedFile);
      
      return uploadedFile;
    } catch (error) {
      onUploadError?.(error);
      throw error;
    } finally {
      setProgress(0);
      setIsUploading(false);
      setUploadingFile(undefined);
    }
  }
 
  return {
    isUploading,
    progress,
    uploadFile,
    uploadedFile,
    uploadingFile,
  };
}

Examples

Plate UI

Refer to the preview above.

Plate Plus

Integration with UploadThing
Use slash commands for quick insertion
Displays clickable placeholders for various media types (image, video, audio, file)
Opens a popover with two tabs when the placeholder is clicked:
- Upload tab: Allows uploading local files directly
- Embed tab: Enables pasting embed links for media content
Image-specific features:
- Better loading rendering and image replacement
- Alignment options
- Expand/collapse view
- Download button
Video-specific features:
- Lazy load
- Alignment options
- Caption support
- View original source
Beautifully crafted UI

Get the code

Plugins

PlaceholderPlugin

Plugin for managing media placeholders during upload. Handles file uploads, drag & drop, and clipboard paste events.

Optionsobject

Collapse all

Configuration for different file types. Default configuration:

{
  audio: {
    maxFileCount: 1,
    maxFileSize: '8MB',
    mediaType: AudioPlugin.key,
    minFileCount: 1,
  },
  blob: {
    maxFileCount: 1,
    maxFileSize: '8MB',
    mediaType: FilePlugin.key,
    minFileCount: 1,
  },
  image: {
    maxFileCount: 3,
    maxFileSize: '4MB',
    mediaType: ImagePlugin.key,
    minFileCount: 1,
  },
  pdf: {
    maxFileCount: 1,
    maxFileSize: '4MB',
    mediaType: FilePlugin.key,
    minFileCount: 1,
  },
  text: {
    maxFileCount: 1,
    maxFileSize: '64KB',
    mediaType: FilePlugin.key,
    minFileCount: 1,
  },
  video: {
    maxFileCount: 1,
    maxFileSize: '16MB',
    mediaType: VideoPlugin.key,
    minFileCount: 1,
  },
}

Disable empty placeholder when no file is uploading.

Default: false

Disable drag and drop file upload functionality.

Default: false

Maximum number of files that can be uploaded at once, if not specified by uploadConfig.

Default: 5

Allow multiple files of the same type to be uploaded.

Default: true

`MediaPluginOptions`

Plugin options used by media plugins.

Attributes

Collapse all

A function to check whether a text string is a URL.

A function to transform the URL.

`ImagePlugin`

Plugin for void image elements. Extends MediaPluginOptions.

OptionsImagePluginOptions

Collapse all

Function to upload image to a server. Receives:

Data URL (string) from FileReader.readAsDataURL
ArrayBuffer from clipboard data Returns:
URL string to uploaded image
Original data URL/ArrayBuffer if no upload needed
Default: Returns original input

Disables file upload on data insertion.

Default: false

Disables URL embed on data insertion.

Default: false

`VideoPlugin`

Plugin for void video elements.

`AudioPlugin`

Plugin for void audio elements.

`FilePlugin`

Plugin for void file elements.

`MediaEmbedPlugin`

Plugin for void media embed elements. Options extends MediaPluginOptions.

API Placeholder

`editor.tf.insert.media()`

Inserts media files into the editor with upload placeholders.

Parameters

Collapse all

Files to upload. Validates against configured file types and limits.

Options for the insert nodes transform.

Optionsobject

Collapse all

Location to insert the media. Defaults to current selection.

Whether to insert a new block after the media.

Default: true

The transform:

Validates files against configured limits (size, count, type)
Creates placeholder elements for each file
Handles multiple file uploads sequentially
Maintains upload history for undo/redo operations
Triggers error handling if validation fails

Error codes:

enum UploadErrorCode {
  INVALID_FILE_TYPE = 400,
  TOO_MANY_FILES = 402,
  INVALID_FILE_SIZE = 403,
  TOO_LESS_FILES = 405,
  TOO_LARGE = 413,
}

`editor.tf.insert.audioPlaceholder`

Inserts a placeholder. Converts to an audio element when completed.

OptionsInsertNodesOptions

Collapse all

Options for the insert nodes transform.

`editor.tf.insert.filePlaceholder`

Inserts a placeholder. Converts to a file element when completed.

OptionsInsertNodesOptions

Options for the insert nodes transform.

`editor.tf.insert.imagePlaceholder`

Inserts a placeholder. Converts to an image element when completed.

OptionsInsertNodesOptions

Options for the insert nodes transform.

`editor.tf.insert.videoPlaceholder`

Inserts a placeholder. Converts to a video element when completed.

OptionsInsertNodesOptions

Options for the insert nodes transform.

`editor.api.placeholder.addUploadingFile()`

Tracks a file that is currently being uploaded.

Parameters

Collapse all

Unique identifier for the placeholder element.

The file being uploaded.

`editor.api.placeholder.getUploadingFile()`

Gets a file that is currently being uploaded.

Parameters

Collapse all

Unique identifier for the placeholder element.

Returns

Collapse all

The uploading file if found, undefined otherwise.

`editor.api.placeholder.removeUploadingFile()`

Removes a file from the uploading tracking state after upload completes or fails.

Parameters

Collapse all

Unique identifier for the placeholder element to remove.

API Media

`parseMediaUrl`

Parameters

Collapse all

The key of the media plugin.

The URL of the media to be parsed.

`submitFloatingMedia`

Parameters

Collapse all

The floating media element to be submitted.

The key of the media plugin.

`EmbedUrlData`

Attributes

Collapse all

The URL of the embedded content.

The provider of the embedded content.

The unique ID for the embedded content.

The component to be rendered for the embedded content.

API Image

`insertImage`

Inserts an image element into the editor.

Parameters

Collapse all

The URL or ArrayBuffer of the image.

Additional options for inserting the image element.

OptionsInsertImageOptions

Collapse all

If true, the image will be inserted in the next block.

`isImageUrl`

Checks if a URL is a valid image URL.

Parameters

Collapse all

The URL to check.

Returnsboolean

Whether the URL is a valid image URL.

`withImageUpload`

Enhances the editor instance with image upload functionality.

Parameters

Collapse all

The plate plugin.

`withImageEmbed`

Enhances the editor instance with image-related functionality.

Parameters

Collapse all

The plate plugin.

API Media Embed

`insertMediaEmbed`

Inserts a media embed element at the current selection.

OptionsInsertMediaEmbedOptions

Collapse all

The URL of the media embed.

Default: ''

The key of the media embed element.

Default: MediaEmbedPlugin.key

Additional options for inserting nodes.

`parseIframeUrl`

Parses the URL of an iframe embed.

Parameters

Collapse all

The URL or embed code of the iframe.

`parseTwitterUrl`

Parses a Twitter URL and extracts the tweet ID.

Parameters

Collapse all

The Twitter URL.

Returns

Collapse all

An object containing the tweet ID and provider if the parsing is successful. Returns undefined if the URL is not valid or does not match any supported video providers.

`parseVideoUrl`

Parses a video URL and extracts the video ID and provider-specific embed URL.

Parameters

Collapse all

The video URL to parse.

ReturnsEmbedUrlData | undefined

An object containing the video ID and provider if parsing is successful, undefined if URL is invalid or unsupported.

API Components

`useResizable`

Handles the resizable properties of a media element.

State

Collapse all

The alignment of the content within the resizable element.

The minimum width that the resizable element can be adjusted to.

The maximum width that the resizable element can be adjusted to.

Function to set the width of the node when resizing.

Function to set the width of the resizable element directly.

The current width of the resizable element (percentage, 'auto', or pixels).

Returnsobject

Collapse all

React reference to the outermost wrapper div.

CSS styles for the wrapper div.

CSS styles for the resizable element.

Callback function called when the element is resized.

`useFloatingMediaEditButton`

Handles the floating media edit button.

Returnsobject

Collapse all

Callback function to handle the button click.

`useFloatingMediaUrlInput`

Handles the URL input field for media elements.

Props

Collapse all

The default value for the URL input field.

Returnsobject

Collapse all

Callback function to handle input changes.

Whether the URL input field should be focused on mount.

The default value for the URL input field.

`useImage`

Returnsobject

Collapse all

The URL of the media element.

The caption string for the image.

Whether the image is draggable.

`useMediaState`

A state hook for a media element.

`useMediaState`

Parameters

Collapse all

Array of URL parsers to parse the media element URL.

EmbedUrlParser: (url: string) => EmbedUrlData | undefined

Returnsobject

Collapse all

The alignment of the media element.

Whether the media element is currently focused.

Whether the media element is currently selected.

Whether the editor is in read-only mode.

The parsed embed data of the media element.

Whether the media element is a tweet.

Whether the media element is a video.

Whether the media element is a YouTube video.

`useMediaToolbarButton`

A behavior hook for a media toolbar button.

`useMediaToolbarButton`

Parameters

Collapse all

The type of media node to insert.

Returnsobject

Collapse all

Callback function that inserts the media node and focuses the editor.

Types

TMediaElement

export interface TMediaElement extends TElement {
  url: string;
  id?: string;
  align?: 'center' | 'left' | 'right';
  isUpload?: boolean;
  name?: string;
  placeholderId?: string;
}

TPlaceholderElement

  mediaType: string;
}

List Mention

On This Page

Features
Installation
Usage
- Caption
- Upload
Examples
- Plate UI
- Plate Plus
Plugins
API Placeholder
API Media
API Image
API Media Embed
API Components
Types
- TMediaElement
- TPlaceholderElement

Build your editor

Production-ready AI template and reusable components.

Media

Features

Media Features

Media Support

Upload

Installation

Usage

Caption

Upload

UploadThing

Custom Implementation

Examples

Plate UI

Plate Plus

Plugins

PlaceholderPlugin

Optionsobject

uploadConfig optional Partial<Record<AllowedFileType, MediaItemConfig>>

uploadConfig optional Partial<Record<AllowedFileType, MediaItemConfig>>

Show child attributes

disableEmptyPlaceholder optional boolean

disableEmptyPlaceholder optional boolean

disableFileDrop optional boolean

disableFileDrop optional boolean

maxFileCount optional number

maxFileCount optional number

multiple optional boolean

multiple optional boolean

MediaPluginOptions

Attributes

isUrl optional function

isUrl optional function

transformUrl optional function

transformUrl optional function

ImagePlugin

OptionsImagePluginOptions

uploadImage optional (dataUrl: string | ArrayBuffer) => Promise<string | ArrayBuffer> | string | ArrayBuffer

uploadImage optional (dataUrl: string | ArrayBuffer) => Promise<string | ArrayBuffer> | string | ArrayBuffer

disableUploadInsert optional boolean

disableUploadInsert optional boolean

disableEmbedInsert optional boolean

disableEmbedInsert optional boolean

VideoPlugin

AudioPlugin

FilePlugin

MediaEmbedPlugin

API Placeholder

editor.tf.insert.media()

Parameters

files FileList

files FileList

options optional object

options optional object

Optionsobject

at optional Path

at optional Path

nextBlock optional boolean

nextBlock optional boolean

editor.tf.insert.audioPlaceholder

OptionsInsertNodesOptions

options InsertNodesOptions

options InsertNodesOptions

editor.tf.insert.filePlaceholder

OptionsInsertNodesOptions

editor.tf.insert.imagePlaceholder

OptionsInsertNodesOptions

editor.tf.insert.videoPlaceholder

OptionsInsertNodesOptions

editor.api.placeholder.addUploadingFile()

Parameters

id string

id string

file File

file File

editor.api.placeholder.getUploadingFile()

Parameters

id string

id string

Returns

File | undefined

`MediaPluginOptions`

`ImagePlugin`

`VideoPlugin`

`AudioPlugin`

`FilePlugin`

`MediaEmbedPlugin`

`editor.tf.insert.media()`

`editor.tf.insert.audioPlaceholder`

`editor.tf.insert.filePlaceholder`

`editor.tf.insert.imagePlaceholder`

`editor.tf.insert.videoPlaceholder`

`editor.api.placeholder.addUploadingFile()`

`editor.api.placeholder.getUploadingFile()`

`editor.api.placeholder.removeUploadingFile()`

`parseMediaUrl`

`submitFloatingMedia`

`EmbedUrlData`

`insertImage`

`isImageUrl`

`withImageUpload`

`withImageEmbed`

`insertMediaEmbed`

`parseIframeUrl`