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
```