0
# Plate Basic Elements
1

2
Plate Basic Elements provides a convenient bundling plugin that combines four essential text editing elements into a single package for the Plate rich-text editor framework. It bundles blockquote, code block, heading, and paragraph plugins with their default configurations, offering a simple way to add basic text editing capabilities to any Plate editor.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { BaseBasicElementsPlugin } from '@udecode/plate-basic-elements';
15
```
16

17
For React-enhanced functionality:
18

19
```typescript
20
import { BasicElementsPlugin } from '@udecode/plate-basic-elements/react';
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { createPlateEditor } from '@udecode/plate/react';
27
import { BasicElementsPlugin } from '@udecode/plate-basic-elements/react';
28

29
// Create editor with basic elements
30
const editor = createPlateEditor({
31
  plugins: [
32
    BasicElementsPlugin,
33
    // ... other plugins
34
  ],
35
});
36

37
// The plugin automatically provides:
38
// - Blockquotes (Cmd+Shift+.)
39
// - Code blocks (Cmd+Alt+8) 
40
// - Headings H1-H3 (Cmd+Alt+1/2/3, Cmd+Shift+1/2/3)
41
// - Paragraphs (Cmd+Alt+0, Cmd+Shift+0)
42
```
43

44
For headless/server-side usage:
45

46
```typescript
47
import { createSlateEditor } from '@udecode/plate';
48
import { BaseBasicElementsPlugin } from '@udecode/plate-basic-elements';
49

50
const editor = createSlateEditor({
51
  plugins: [
52
    BaseBasicElementsPlugin,
53
    // ... other plugins
54
  ],
55
});
56
```
57

58
## Architecture
59

60
The package provides two plugin variants that bundle existing Plate plugins:
61

62
- **BaseBasicElementsPlugin**: Headless Slate.js integration without React dependencies
63
- **BasicElementsPlugin**: Full React integration with keyboard shortcuts and UI components
64

65
Both plugins are convenience wrappers that include four pre-configured plugins from separate packages.
66

67
## Capabilities
68

69
### Headless Basic Elements Plugin
70

71
The core plugin that bundles all basic elements functionality without React dependencies.
72

73
```typescript { .api }
74
const BaseBasicElementsPlugin: SlatePlugin;
75
```
76

77
**Plugin Configuration:**
78
- **Plugin Key**: `'basicElements'`
79
- **Sub-plugins**: Includes `BaseBlockquotePlugin`, `BaseCodeBlockPlugin`, `BaseHeadingPlugin`, `BaseParagraphPlugin`
80

81
### React Basic Elements Plugin
82

83
React-enhanced plugin with keyboard shortcuts and UI components.
84

85
```typescript { .api }
86
const BasicElementsPlugin: PlatePlugin;
87
```
88

89
**Plugin Configuration:**
90
- **Plugin Key**: `'basicElements'`
91
- **Sub-plugins**: Includes `BlockquotePlugin`, `CodeBlockPlugin`, `HeadingPlugin`, `ParagraphPlugin`
92
- **Keyboard Shortcuts**: Inherits all shortcuts from constituent plugins
93

94
## Bundled Plugin Details
95

96
This package bundles the following plugins from separate packages:
97

98
### Blockquote Plugin
99
- **Package**: @udecode/plate-block-quote  
100
- **Plugin Key**: `'blockquote'`
101
- **React Shortcut**: `Cmd+Shift+.`
102
- **Functionality**: Blockquote elements for quotations and emphasis
103

104
### Code Block Plugin
105
- **Package**: @udecode/plate-code-block
106
- **Plugin Key**: `'code_block'`
107
- **React Shortcut**: `Cmd+Alt+8`
108
- **Functionality**: Multi-line code blocks with optional syntax highlighting
109

110
### Heading Plugin
111
- **Package**: @udecode/plate-heading
112
- **Plugin Key**: `'heading'`
113
- **React Shortcuts**: `Cmd+Alt+1/2/3`, `Cmd+Shift+1/2/3` (H1-H3 only)
114
- **Functionality**: Heading elements (H1-H6)
115

116
### Paragraph Plugin
117
- **Package**: @udecode/plate (core package)
118
- **Plugin Key**: `'p'`
119
- **React Shortcuts**: `Cmd+Alt+0`, `Cmd+Shift+0`
120
- **Functionality**: Standard paragraph elements for text content
121

122
## Accessing Individual Plugin APIs
123

124
The basic-elements package only exports the two bundled plugins. To access individual plugin APIs, transforms, types, or configurations, import directly from the source packages:
125

126
```typescript
127
// For blockquote functionality
128
import { toggleBlockquote, withBlockquote } from '@udecode/plate-block-quote';
129

130
// For code block functionality  
131
import { 
132
  insertCodeBlock, 
133
  toggleCodeBlock,
134
  type TCodeBlockElement,
135
  type CodeBlockConfig 
136
} from '@udecode/plate-code-block';
137

138
// For heading functionality
139
import { 
140
  isHeading,
141
  HEADING_KEYS,
142
  type HeadingConfig
143
} from '@udecode/plate-heading';
144
```
145

146
## Custom Configuration
147

148
To customize individual plugins while using the bundled approach, configure them separately:
149

150
```typescript
151
import { createPlateEditor } from '@udecode/plate/react';
152
import { BlockquotePlugin } from '@udecode/plate-block-quote/react';
153
import { CodeBlockPlugin } from '@udecode/plate-code-block/react';
154
import { HeadingPlugin } from '@udecode/plate-heading/react';
155
import { ParagraphPlugin } from '@udecode/plate/react';
156

157
// Custom configuration approach
158
const editor = createPlateEditor({
159
  plugins: [
160
    BlockquotePlugin,
161
    CodeBlockPlugin.configure({ 
162
      options: { 
163
        defaultLanguage: 'typescript' 
164
      } 
165
    }),
166
    HeadingPlugin.configure({
167
      options: {
168
        levels: [1, 2, 3] // Only H1-H3
169
      }
170
    }),
171
    ParagraphPlugin,
172
  ],
173
});
174
```
175

176
## Use Cases
177

178
### Quick Setup
179
Use `BasicElementsPlugin` when you want standard basic elements with default settings:
180

181
```typescript
182
import { BasicElementsPlugin } from '@udecode/plate-basic-elements/react';
183

184
const plugins = [BasicElementsPlugin];
185
```
186

187
### Custom Configuration
188
Use individual plugins when you need custom configuration:
189

190
```typescript
191
import { 
192
  BlockquotePlugin,
193
  CodeBlockPlugin, 
194
  HeadingPlugin,
195
  ParagraphPlugin
196
} from their respective packages;
197

198
const plugins = [
199
  BlockquotePlugin,
200
  CodeBlockPlugin.configure({ /* custom options */ }),
201
  HeadingPlugin.configure({ /* custom options */ }),
202
  ParagraphPlugin,
203
];
204
```
205

206
### Headless Usage
207
Use `BaseBasicElementsPlugin` for server-side rendering or custom UI:
208

209
```typescript
210
import { BaseBasicElementsPlugin } from '@udecode/plate-basic-elements';
211

212
const editor = createSlateEditor({
213
  plugins: [BaseBasicElementsPlugin]
214
});
215
```
216

217
## Dependencies
218

219
This package has peer dependencies on:
220
- `@udecode/plate` (>=48.0.0)
221
- `react` (>=18.0.0) - for React plugin only
222
- `react-dom` (>=18.0.0) - for React plugin only
223

224
And direct dependencies on the bundled plugin packages:
225
- `@udecode/plate-block-quote` (48.0.0)
226
- `@udecode/plate-code-block` (48.0.0) 
227
- `@udecode/plate-heading` (48.0.0)