Caption

PreviousNext

Add captions to media elements like images, videos, and files.

Caption
Loading...
Files
components/demo.tsx
'use client';

import * as React from 'react';

import { Plate, usePlateEditor } from 'platejs/react';

import { EditorKit } from '@/components/editor/editor-kit';
import { Editor, EditorContainer } from '@/components/ui/editor';

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

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

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

Features

  • Add captions to images, videos, audio files, and other media elements.
  • Arrow navigation selects caption within a block.
  • Inline caption editing with textarea component.

Kit Usage

Installation

The fastest way to add caption functionality is with the MediaKit, which includes the pre-configured CaptionPlugin along with media plugins and their Plate UI components.

'use client';
 
import { CaptionPlugin } from '@platejs/caption/react';
import {
  AudioPlugin,
  FilePlugin,
  ImagePlugin,
  MediaEmbedPlugin,
  PlaceholderPlugin,
  VideoPlugin,
} from '@platejs/media/react';
import { KEYS } from 'platejs';
 
import { AudioElement } from '@/components/ui/media-audio-node';
import { MediaEmbedElement } from '@/components/ui/media-embed-node';
import { FileElement } from '@/components/ui/media-file-node';
import { ImageElement } from '@/components/ui/media-image-node';
import { PlaceholderElement } from '@/components/ui/media-placeholder-node';
import { MediaPreviewDialog } from '@/components/ui/media-preview-dialog';
import { MediaUploadToast } from '@/components/ui/media-upload-toast';
import { VideoElement } from '@/components/ui/media-video-node';
 
export const MediaKit = [
  ImagePlugin.configure({
    options: { disableUploadInsert: true },
    render: { afterEditable: MediaPreviewDialog, node: ImageElement },
  }),
  MediaEmbedPlugin.withComponent(MediaEmbedElement),
  VideoPlugin.withComponent(VideoElement),
  AudioPlugin.withComponent(AudioElement),
  FilePlugin.withComponent(FileElement),
  PlaceholderPlugin.configure({
    options: { disableEmptyPlaceholder: true },
    render: { afterEditable: MediaUploadToast, node: PlaceholderElement },
  }),
  CaptionPlugin.configure({
    options: {
      query: {
        allow: [KEYS.img, KEYS.video, KEYS.audio, KEYS.file, KEYS.mediaEmbed],
      },
    },
  }),
];
  • Caption: Renders caption components for media elements.

Add Kit

import { createPlateEditor } from 'platejs/react';
import { MediaKit } from '@/components/editor/plugins/media-kit';
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...MediaKit,
  ],
});

Manual Usage

Installation

pnpm add @platejs/caption

Add Plugin

import { CaptionPlugin } from '@platejs/caption/react';
import { createPlateEditor } from 'platejs/react';
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    CaptionPlugin,
  ],
});

Configure Plugin

Configure which media plugins should support captions:

import { KEYS } from 'platejs';
import { CaptionPlugin } from '@platejs/caption/react';
import {
  AudioPlugin,
  FilePlugin,
  ImagePlugin,
  MediaEmbedPlugin,
  VideoPlugin,
} from '@platejs/media/react';
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ImagePlugin,
    VideoPlugin,
    AudioPlugin,
    FilePlugin,
    MediaEmbedPlugin,
    CaptionPlugin.configure({
      options: {
        query: {
          allow: [KEYS.img, KEYS.video, KEYS.audio, KEYS.file, KEYS.mediaEmbed],
        },
      },
    }),
  ],
});
  • query.allow: Array of plugin keys that support captions.

Plugins

CaptionPlugin

Plugin for adding caption functionality to media elements.

Options

Collapse all

    Configuration for which plugins support captions.

    Path to focus at the end of the caption.

    • Default: null

    Path to focus at the start of the caption.

    • Default: null

    ID of the currently visible caption.

    • Default: null

Types

TCaptionElement

Extends TElement.

Attributes

Collapse all

    Caption value as an array of descendant nodes.

Components

<Caption>

Props

Collapse all

    Options for the caption component.

    State for the caption component.

    Optionsobject

    Collapse all

      Whether the caption component is in read-only mode.

<CaptionTextarea>

Props

Collapse all

    State for the caption textarea.

Block SelectionEmoji