or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-plugin.mdhooks-and-utilities.mdindex.mdreact-components.md
tile.json

tessl/npm-udecode--plate-caption

Primitive React components and hooks for implementing caption functionality in Plate rich-text editors.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@udecode/plate-caption@49.0.x

To install, run

npx @tessl/cli install tessl/npm-udecode--plate-caption@49.0.0

index.mddocs/

Plate Caption

Plate Caption provides primitive React components and hooks for implementing caption functionality in rich-text editors built with the Plate framework. It enables users to add, edit, and manage captions for media elements (like images) within editor content, with support for keyboard navigation, focus management, and customizable styling.

Package Information

  • Package Name: @udecode/plate-caption
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @udecode/plate-caption

Core Imports

Main package exports (core plugin functionality):

import { BaseCaptionPlugin, withCaption, type CaptionConfig } from "@udecode/plate-caption";

React-specific exports:

import { 
  CaptionPlugin, 
  Caption, 
  CaptionTextarea,
  useCaptionString,
  showCaption 
} from "@udecode/plate-caption/react";

For CommonJS:

const { BaseCaptionPlugin, withCaption } = require("@udecode/plate-caption");
const { CaptionPlugin, Caption, CaptionTextarea } = require("@udecode/plate-caption/react");

Type imports:

import type { TextareaAutosizeProps } from "react-textarea-autosize";

Basic Usage

import { createPlateEditor, PlateContent } from "@udecode/plate/react";
import { CaptionPlugin, Caption, CaptionTextarea } from "@udecode/plate-caption/react";

// Configure editor with caption plugin
const editor = createPlateEditor({
  plugins: [
    CaptionPlugin.configure({
      options: {
        query: { allow: ['img', 'media'] } // Enable captions for image and media elements
      }
    })
    // ... other plugins
  ]
});

// Use in JSX
function MediaWithCaption() {
  return (
    <div>
      <img src="example.jpg" />
      <Caption>
        <CaptionTextarea placeholder="Enter caption..." />
      </Caption>
    </div>
  );
}

Architecture

Plate Caption is built around several key components:

  • Core Plugin System: BaseCaptionPlugin integrates with Plate's plugin architecture to provide caption state management, focus handling, and editor enhancements
  • React Integration: CaptionPlugin wraps the core plugin for React compatibility, while components provide the UI layer
  • State Management: Plugin maintains visibility state, focus paths, and element-specific caption data
  • Component System: Primitive components (Caption, CaptionTextarea) that can be styled and customized
  • Focus Management: Sophisticated keyboard navigation between editor content and caption fields

Capabilities

Core Plugin System

Foundation plugin that integrates caption functionality into Plate editors with configurable options for element types, visibility, and focus management.

const BaseCaptionPlugin = createTSlatePlugin<CaptionConfig>({
  key: KEYS.caption,
  options: {
    focusEndPath: Path | null,
    focusStartPath: Path | null,
    query: { allow: string[] },
    visibleId: string | null
  }
});

type CaptionConfig = PluginConfig<
  'caption',
  {
    focusEndPath: Path | null;
    focusStartPath: Path | null;
    query: { allow: string[] };
    visibleId: string | null;
  },
  {},
  {},
  {
    isVisible?: (elementId: string) => boolean;
  }
>;

function withCaption(editor: SlateEditor): SlateEditor;

Core Plugin System

React Components

Primitive React components for rendering caption UI with full customization support and accessibility features.

const CaptionPlugin = toPlatePlugin(BaseCaptionPlugin);

function Caption(props: CaptionProps): JSX.Element;
function CaptionTextarea(props: ComponentProps<typeof TextareaAutosize>): JSX.Element;
function TextareaAutosize(props: TextareaAutosizeProps): JSX.Element;

interface CaptionProps extends React.ComponentPropsWithoutRef<'figcaption'> {
  options?: CaptionOptions;
}

interface CaptionOptions {
  readOnly?: boolean;
}

React Components

Hooks and Utilities

React hooks for component state management and utility functions for programmatic caption control.

function useCaptionString(): string;
function useCaptionState(options?: CaptionOptions): {
  captionString: string;
  hidden: boolean;
  readOnly: boolean;
  selected: boolean;
};
function showCaption(editor: SlateEditor, element: TElement): void;

Hooks and Utilities

Types

Core types used throughout the caption system:

type CaptionConfig = PluginConfig<
  'caption',
  {
    /** When defined, focus end of caption textarea with the same path. */
    focusEndPath: Path | null;
    /** When defined, focus start of caption textarea with the same path. */
    focusStartPath: Path | null;
    query: {
      /** Plugin keys to enable caption. */
      allow: string[];
    };
    visibleId: string | null;
  },
  {},
  {},
  {
    isVisible?: (elementId: string) => boolean;
  }
>;

interface CaptionOptions {
  readOnly?: boolean;
}

interface CaptionProps extends React.ComponentPropsWithoutRef<'figcaption'> {
  options?: CaptionOptions;
}

interface TCaptionElement extends TElement {
  caption?: TElement[];
}

interface TextareaAutosizeProps {
  maxRows?: number;
  minRows?: number;
  onHeightChange?: (height: number, meta: { rowHeight: number }) => void;
  cacheMeasurements?: boolean;
  [key: string]: any; // Standard textarea props
}