0
# Plate Alignment
1

2
Plate Alignment is a text alignment plugin for the Plate rich-text editor framework. It provides both headless core functionality and React components to enable text alignment capabilities (left, center, right, justify, start, end) in Plate-based editors. The plugin supports HTML parsing, integrates seamlessly with Plate's plugin system, and offers transform functions for programmatic alignment control.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { BaseTextAlignPlugin, setAlign, type Alignment } from "@udecode/plate-alignment";
15
```
16

17
For React functionality:
18

19
```typescript
20
import { TextAlignPlugin } from "@udecode/plate-alignment/react";
21
```
22

23
CommonJS:
24

25
```javascript
26
const { BaseTextAlignPlugin, setAlign } = require("@udecode/plate-alignment");
27
const { TextAlignPlugin } = require("@udecode/plate-alignment/react");
28
```
29

30
## Basic Usage
31

32
```typescript
33
import { createPlateEditor } from "@udecode/plate";
34
import { BaseTextAlignPlugin, setAlign } from "@udecode/plate-alignment";
35

36
// Create editor with alignment plugin
37
const editor = createPlateEditor({
38
  plugins: [
39
    BaseTextAlignPlugin.configure({
40
      // Plugin configuration options
41
    }),
42
  ],
43
});
44

45
// Programmatically set alignment
46
setAlign(editor, "center");
47
setAlign(editor, "right");
48
setAlign(editor, "justify");
49
```
50

51
For React applications:
52

53
```typescript
54
import { Plate } from "@udecode/plate/react";
55
import { TextAlignPlugin } from "@udecode/plate-alignment/react";
56

57
function MyEditor() {
58
  return (
59
    <Plate
60
      plugins={[
61
        TextAlignPlugin.configure({
62
          // Plugin configuration options
63
        }),
64
      ]}
65
    >
66
      {/* Editor components */}
67
    </Plate>
68
  );
69
}
70
```
71

72
## Architecture
73

74
The package is structured around the Plate plugin architecture:
75

76
- **BaseTextAlignPlugin**: Core headless plugin that provides the alignment functionality
77
- **TextAlignPlugin**: React wrapper that extends the base plugin for React applications
78
- **Transform Functions**: Programmatic API for setting alignment via `setAlign` function
79
- **HTML Support**: Automatic parsing of `textAlign` CSS styles during HTML deserialization
80
- **Node Properties**: Alignment stored as `align` property on editor nodes
81

82
## Capabilities
83

84
### Base Text Alignment Plugin
85

86
Core headless plugin that adds text alignment functionality to any Plate editor.
87

88
```typescript { .api }
89
/**
90
 * Creates a plugin that adds alignment functionality to the editor.
91
 * Provides HTML parsing, node property management, and transform integration.
92
 */
93
const BaseTextAlignPlugin: SlatePlugin;
94
```
95

96
**Plugin Configuration:**
97

98
The plugin is created with these specific configuration options:
99

100
```typescript
101
BaseTextAlignPlugin = createSlatePlugin({
102
  key: KEYS.textAlign,
103
  inject: {
104
    isBlock: true,
105
    nodeProps: {
106
      defaultNodeValue: 'start',
107
      nodeKey: 'align',
108
      styleKey: 'textAlign',
109
      validNodeValues: ['start', 'left', 'center', 'right', 'end', 'justify'],
110
    },
111
    targetPlugins: [KEYS.p],
112
  },
113
});
114
```
115

116
- **Key**: Uses `KEYS.textAlign` from Plate
117
- **Default Value**: `'start'` - when set to default, the property is removed
118
- **Valid Values**: `['start', 'left', 'center', 'right', 'end', 'justify']`
119
- **Target Plugins**: Applies to paragraph plugins (`KEYS.p`) by default
120
- **Node Property**: Stores alignment in `align` property on editor nodes
121
- **Style Mapping**: Maps to CSS `textAlign` property during HTML parsing
122

123
**HTML Deserialization:**
124
Automatically parses `textAlign` CSS styles from HTML elements during editor initialization.
125

126
**Extended Transforms:**
127
- `set`: Transform function for setting alignment (bound to `setAlign`)
128

129
### Set Alignment Transform
130

131
Programmatically sets text alignment on editor nodes.
132

133
```typescript { .api }
134
/**
135
 * Transform function to set text alignment on editor nodes
136
 * @param editor - The Slate editor instance
137
 * @param value - The alignment value to set
138
 * @param setNodesOptions - Optional configuration for setNodes operation
139
 */
140
function setAlign(
141
  editor: SlateEditor,
142
  value: Alignment,
143
  setNodesOptions?: SetNodesOptions
144
): void;
145
```
146

147
**Behavior:**
148
- If `value` equals the default alignment (`'start'`), calls `editor.tf.unsetNodes()` to remove the alignment property completely
149
- Otherwise, calls `editor.tf.setNodes()` to set the alignment property on matching nodes
150
- Uses `getInjectMatch()` to determine which nodes should be targeted based on the plugin's inject configuration
151
- Supports all `SetNodesOptions` for advanced node targeting (at, match, etc.)
152

153
**Usage Example:**
154

155
```typescript
156
import { setAlign } from "@udecode/plate-alignment";
157
import { useEditorRef } from "@udecode/plate/react";
158

159
function AlignmentControls() {
160
  const editor = useEditorRef();
161

162
  const handleAlign = (alignment: Alignment) => {
163
    setAlign(editor, alignment);
164
  };
165

166
  return (
167
    <div>
168
      <button onClick={() => handleAlign("left")}>Left</button>
169
      <button onClick={() => handleAlign("center")}>Center</button>
170
      <button onClick={() => handleAlign("right")}>Right</button>
171
      <button onClick={() => handleAlign("justify")}>Justify</button>
172
    </div>
173
  );
174
}
175
```
176

177
### React Text Alignment Plugin
178

179
React-compatible version of the base alignment plugin for use in React applications.
180

181
```typescript { .api }
182
/**
183
 * React-compatible text alignment plugin
184
 * Wraps BaseTextAlignPlugin with React-specific functionality
185
 */
186
const TextAlignPlugin: PlatePlugin;
187
```
188

189
**Usage in React Editor:**
190

191
```typescript
192
import { useEditorRef } from "@udecode/plate/react";
193
import { TextAlignPlugin, setAlign } from "@udecode/plate-alignment/react";
194

195
function AlignmentToolbar() {
196
  const editor = useEditorRef();
197

198
  const handleAlign = (value: Alignment) => {
199
    setAlign(editor, value);
200
    // Focus editor after setting alignment
201
    editor.tf.focus();
202
  };
203

204
  return (
205
    <div>
206
      <button onClick={() => handleAlign("left")}>Align Left</button>
207
      <button onClick={() => handleAlign("center")}>Align Center</button>
208
      <button onClick={() => handleAlign("right")}>Align Right</button>
209
      <button onClick={() => handleAlign("justify")}>Justify</button>
210
    </div>
211
  );
212
}
213
```
214

215
## Types
216

217
```typescript { .api }
218
/**
219
 * Union type defining valid text alignment values
220
 */
221
type Alignment = 'center' | 'end' | 'justify' | 'left' | 'right' | 'start';
222

223
/**
224
 * Core Slate editor interface extended with Plate functionality
225
 * Includes plugin management, transforms, and API methods
226
 */
227
interface SlateEditor extends BaseEditor {
228
  api: EditorApi & UnionToIntersection<InferApi<CorePlugin>>;
229
  tf: EditorTransforms & UnionToIntersection<InferTransforms<CorePlugin>>;
230
  transforms: EditorTransforms & UnionToIntersection<InferTransforms<CorePlugin>>;
231
  plugins: Record<string, AnyEditorPlugin>;
232
  getPlugin<C extends AnyPluginConfig>(plugin: WithRequiredKey<C>): EditorPlugin<C>;
233
  // ... additional Plate-specific methods
234
}
235

236
/**
237
 * Options for setNodes operations supporting query matching and node targeting
238
 */
239
interface SetNodesOptions<V extends Value = Value> {
240
  /** Match specific nodes using predicates */
241
  match?: Predicate<NodeIn<V>>;
242
  /** Comparison function for property updates */
243
  compare?: PropsCompare;
244
  /** Merge function for combining properties */
245
  merge?: PropsMerge;
246
  /** Whether to split text nodes */
247
  split?: boolean;
248
  /** Apply only to text nodes in non-void nodes */
249
  marks?: boolean;
250
  /** Match by node ID */
251
  id?: boolean | string;
252
  /** Match block nodes only */
253
  block?: boolean;
254
  // ... additional query options
255
}
256

257
/**
258
 * Core headless plugin interface for Slate functionality
259
 */
260
interface SlatePlugin<C extends AnyPluginConfig = PluginConfig> extends BasePlugin<C> {
261
  /** Unique plugin identifier */
262
  key: C['key'];
263
  /** Extend editor with custom functionality */
264
  extendEditor?: ExtendEditor<WithAnyKey<C>>;
265
  /** Plugin injection configuration */
266
  inject: {
267
    nodeProps?: InjectNodeProps<WithAnyKey<C>>;
268
    targetPlugins?: string[];
269
    // ... additional injection options
270
  };
271
  /** Parser configuration for HTML/markdown */
272
  parsers: { /* parser configuration */ };
273
  // ... additional plugin properties
274
}
275

276
/**
277
 * React-compatible plugin interface extending SlatePlugin with React features
278
 */
279
interface PlatePlugin<C extends AnyPluginConfig = PluginConfig> extends SlatePlugin<C> {
280
  /** React hooks for component lifecycle */
281
  useHooks?: UseHooks<WithAnyKey<C>>;
282
  /** DOM event handlers */
283
  handlers: DOMHandlers<WithAnyKey<C>> & {
284
    onChange?: OnChange<WithAnyKey<C>>;
285
  };
286
  /** React component rendering */
287
  render: { /* render configuration */ };
288
  // ... additional React-specific properties
289
}
290
```