0
# Plate Caption
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @udecode/plate-caption
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @udecode/plate-caption`
10

11
## Core Imports
12

13
Main package exports (core plugin functionality):
14

15
```typescript
16
import { BaseCaptionPlugin, withCaption, type CaptionConfig } from "@udecode/plate-caption";
17
```
18

19
React-specific exports:
20

21
```typescript
22
import { 
23
  CaptionPlugin, 
24
  Caption, 
25
  CaptionTextarea,
26
  useCaptionString,
27
  showCaption 
28
} from "@udecode/plate-caption/react";
29
```
30

31
For CommonJS:
32

33
```javascript
34
const { BaseCaptionPlugin, withCaption } = require("@udecode/plate-caption");
35
const { CaptionPlugin, Caption, CaptionTextarea } = require("@udecode/plate-caption/react");
36
```
37

38
Type imports:
39

40
```typescript
41
import type { TextareaAutosizeProps } from "react-textarea-autosize";
42
```
43

44
## Basic Usage
45

46
```typescript
47
import { createPlateEditor, PlateContent } from "@udecode/plate/react";
48
import { CaptionPlugin, Caption, CaptionTextarea } from "@udecode/plate-caption/react";
49

50
// Configure editor with caption plugin
51
const editor = createPlateEditor({
52
  plugins: [
53
    CaptionPlugin.configure({
54
      options: {
55
        query: { allow: ['img', 'media'] } // Enable captions for image and media elements
56
      }
57
    })
58
    // ... other plugins
59
  ]
60
});
61

62
// Use in JSX
63
function MediaWithCaption() {
64
  return (
65
    <div>
66
      <img src="example.jpg" />
67
      <Caption>
68
        <CaptionTextarea placeholder="Enter caption..." />
69
      </Caption>
70
    </div>
71
  );
72
}
73
```
74

75
## Architecture
76

77
Plate Caption is built around several key components:
78

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

85
## Capabilities
86

87
### Core Plugin System
88

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

91
```typescript { .api }
92
const BaseCaptionPlugin = createTSlatePlugin<CaptionConfig>({
93
  key: KEYS.caption,
94
  options: {
95
    focusEndPath: Path | null,
96
    focusStartPath: Path | null,
97
    query: { allow: string[] },
98
    visibleId: string | null
99
  }
100
});
101

102
type CaptionConfig = PluginConfig<
103
  'caption',
104
  {
105
    focusEndPath: Path | null;
106
    focusStartPath: Path | null;
107
    query: { allow: string[] };
108
    visibleId: string | null;
109
  },
110
  {},
111
  {},
112
  {
113
    isVisible?: (elementId: string) => boolean;
114
  }
115
>;
116

117
function withCaption(editor: SlateEditor): SlateEditor;
118
```
119

120
[Core Plugin System](./core-plugin.md)
121

122
### React Components
123

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

126
```typescript { .api }
127
const CaptionPlugin = toPlatePlugin(BaseCaptionPlugin);
128

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

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

137
interface CaptionOptions {
138
  readOnly?: boolean;
139
}
140
```
141

142
[React Components](./react-components.md)
143

144
### Hooks and Utilities
145

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

148
```typescript { .api }
149
function useCaptionString(): string;
150
function useCaptionState(options?: CaptionOptions): {
151
  captionString: string;
152
  hidden: boolean;
153
  readOnly: boolean;
154
  selected: boolean;
155
};
156
function showCaption(editor: SlateEditor, element: TElement): void;
157
```
158

159
[Hooks and Utilities](./hooks-and-utilities.md)
160

161
## Types
162

163
Core types used throughout the caption system:
164

165
```typescript { .api }
166
type CaptionConfig = PluginConfig<
167
  'caption',
168
  {
169
    /** When defined, focus end of caption textarea with the same path. */
170
    focusEndPath: Path | null;
171
    /** When defined, focus start of caption textarea with the same path. */
172
    focusStartPath: Path | null;
173
    query: {
174
      /** Plugin keys to enable caption. */
175
      allow: string[];
176
    };
177
    visibleId: string | null;
178
  },
179
  {},
180
  {},
181
  {
182
    isVisible?: (elementId: string) => boolean;
183
  }
184
>;
185

186
interface CaptionOptions {
187
  readOnly?: boolean;
188
}
189

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

194
interface TCaptionElement extends TElement {
195
  caption?: TElement[];
196
}
197

198
interface TextareaAutosizeProps {
199
  maxRows?: number;
200
  minRows?: number;
201
  onHeightChange?: (height: number, meta: { rowHeight: number }) => void;
202
  cacheMeasurements?: boolean;
203
  [key: string]: any; // Standard textarea props
204
}
205
```