0
# Plate Line Height Plugin
1

2
A line height plugin for Plate, a rich-text editor framework built on Slate.js and React. This plugin enables developers to apply custom line spacing to block elements such as paragraphs and headings by injecting line height properties into targeted elements. It supports HTML deserialization, provides configurable defaults, and includes transform functions for programmatic control.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { BaseLineHeightPlugin, setLineHeight } from "@udecode/plate-line-height";
15
import { LineHeightPlugin } from "@udecode/plate-line-height/react";
16
import type { SlateEditor, SetNodesOptions } from "@udecode/plate";
17
```
18

19
For CommonJS:
20

21
```javascript
22
const { BaseLineHeightPlugin, setLineHeight } = require("@udecode/plate-line-height");
23
const { LineHeightPlugin } = require("@udecode/plate-line-height/react");
24
```
25

26
## Basic Usage
27

28
```typescript
29
import { Plate } from "@udecode/plate/react";
30
import { LineHeightPlugin } from "@udecode/plate-line-height/react";
31

32
// Add to your Plate editor
33
const editor = Plate.create({
34
  plugins: [
35
    LineHeightPlugin,
36
    // ... other plugins
37
  ],
38
});
39

40
// Programmatically set line height
41
import { setLineHeight } from "@udecode/plate-line-height";
42
setLineHeight(editor, 2.0); // Sets line height to 2.0
43
```
44

45
## Architecture
46

47
The plugin consists of three main components:
48

49
- **BaseLineHeightPlugin**: Core plugin implementation for base Slate.js integration
50
- **LineHeightPlugin**: React-compatible version using `toPlatePlugin` wrapper  
51
- **Transform Functions**: Utilities for programmatically setting line heights
52

53
The plugin works by:
54
1. Injecting a `lineHeight` property into block elements (paragraphs by default)
55
2. Deserializing `line-height` CSS properties from HTML during paste operations
56
3. Providing transform functions to set/unset line height values programmatically
57
4. Using a default value of 1.5 when no explicit line height is set
58

59
## Capabilities
60

61
### Base Line Height Plugin
62

63
Core plugin implementation that provides line height functionality for Slate.js editors.
64

65
```typescript { .api }
66
import { createSlatePlugin, KEYS } from '@udecode/plate';
67

68
/**
69
 * Core line height plugin that provides line height functionality for block elements.
70
 * Targets paragraph blocks by default with a default line height of 1.5.
71
 * Supports HTML deserialization of line-height CSS properties from pasted HTML.
72
 */
73
export const BaseLineHeightPlugin: SlatePlugin;
74
```
75

76
Configuration options:
77
- **Plugin Key**: `KEYS.lineHeight`
78
- **Default Value**: 1.5
79
- **Target Elements**: Paragraph elements (`KEYS.p`) by default
80
- **Node Property**: `lineHeight`
81
- **Block-level**: Yes (`isBlock: true`)
82

83
### React Line Height Plugin
84

85
React-compatible version of the base plugin for use in Plate React applications.
86

87
```typescript { .api }
88
import { toPlatePlugin } from '@udecode/plate/react';
89

90
/**
91
 * React-compatible version of BaseLineHeightPlugin.
92
 * Created by wrapping BaseLineHeightPlugin with toPlatePlugin.
93
 */
94
export const LineHeightPlugin: PlatePlugin;
95
```
96

97
### Set Line Height Transform
98

99
Transform function to programmatically set line height on selected elements.
100

101
```typescript { .api }
102
import {
103
  type SetNodesOptions,
104
  type SlateEditor,
105
  getInjectMatch,
106
  KEYS,
107
} from '@udecode/plate';
108

109
/**
110
 * Transform function to set line height on selected elements.
111
 * If value equals the default (1.5), removes the line height property.
112
 * Otherwise sets the line height property on matching nodes.
113
 * 
114
 * @param editor - SlateEditor instance
115
 * @param value - Line height value (number)
116
 * @param setNodesOptions - Optional SetNodesOptions for controlling the operation
117
 */
118
export const setLineHeight = (
119
  editor: SlateEditor,
120
  value: number,
121
  setNodesOptions?: SetNodesOptions
122
): void;
123
```
124

125
**Usage Examples:**
126

127
```typescript
128
import { setLineHeight } from "@udecode/plate-line-height";
129

130
// Set line height to 2.0
131
setLineHeight(editor, 2.0);
132

133
// Reset to default (removes the line height property)
134
setLineHeight(editor, 1.5);
135

136
// Set line height with specific options
137
setLineHeight(editor, 1.8, {
138
  at: editor.selection, // Apply to current selection
139
  match: (n) => n.type === 'paragraph' // Only apply to paragraphs
140
});
141
```
142

143
## Types
144

145
```typescript { .api }
146
import type {
147
  SlateEditor,
148
  SetNodesOptions,
149
  SlatePlugin,
150
  PlatePlugin
151
} from '@udecode/plate';
152

153
// The core types used by this plugin are imported from @udecode/plate:
154
// - SlateEditor: The main editor instance with transform methods (tf.setNodes, tf.unsetNodes)
155
// - SetNodesOptions: Options for controlling node operations (at, match, etc.)
156
// - SlatePlugin: Base plugin type for Slate integration
157
// - PlatePlugin: React-compatible plugin type wrapped with toPlatePlugin
158
```
159

160
## HTML Integration
161

162
The plugin automatically handles HTML deserialization when pasting content. It includes a parser that extracts `line-height` CSS properties from HTML elements and applies them to the corresponding Plate nodes.
163

164
```html
165
<!-- This HTML will be automatically parsed -->
166
<p style="line-height: 2.0;">This paragraph has custom line height</p>
167
<div style="line-height: 1.25;">This div also gets line height applied</div>
168
```
169

170
The parser implementation:
171
- Checks for `element.style.lineHeight` on pasted HTML elements
172
- Extracts the line-height value and applies it as a node property
173
- Works with any HTML element that has a `line-height` style attribute
174
- Integrates seamlessly with Plate's HTML deserialization system
175

176
```typescript
177
// Parser logic (internal implementation)
178
parse: ({ element }) => {
179
  if (element.style.lineHeight) {
180
    return {
181
      [editor.getType(plugin.key)]: element.style.lineHeight,
182
    };
183
  }
184
}
185
```