0
# Plate Keyboard Input Plugin
1

2
The @udecode/plate-kbd package provides keyboard input formatting support for the Plate rich-text editor framework. It enables rendering keyboard shortcuts and key combinations as styled inline elements within text content, making it ideal for technical documentation, tutorials, and help content that needs to clearly indicate keyboard shortcuts.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { BaseKbdPlugin } from "@udecode/plate-kbd";
15

16
// For React-specific usage
17
import { KbdPlugin } from "@udecode/plate-kbd/react";
18
```
19

20
CommonJS:
21

22
```javascript
23
const { BaseKbdPlugin } = require("@udecode/plate-kbd");
24

25
// For React-specific usage  
26
const { KbdPlugin } = require("@udecode/plate-kbd/react");
27
```
28

29
## Package Exports
30

31
The package provides dual export structure:
32

33
- **Main entry** (`@udecode/plate-kbd`): Core plugin without React dependencies
34
- **React entry** (`@udecode/plate-kbd/react`): React-enhanced plugin version
35

36
Both CommonJS (`require`) and ES modules (`import`) are supported.
37

38
## Basic Usage
39

40
```typescript
41
// Import dependencies
42
import { createPlateEditor } from "@udecode/plate/react";
43
import { Plate } from "@udecode/plate/react";
44
import { KbdPlugin } from "@udecode/plate-kbd/react";
45

46
// Register the plugin with Plate
47
const editor = createPlateEditor({
48
  plugins: [
49
    // ... other plugins
50
    KbdPlugin,
51
  ],
52
});
53

54
// Use in JSX
55
function MyEditor() {
56
  return (
57
    <Plate editor={editor}>
58
      <div>
59
        Press <kbd>Ctrl+C</kbd> to copy or <kbd>Cmd+V</kbd> to paste.
60
      </div>
61
    </Plate>
62
  );
63
}
64
```
65

66
**Note**: The `createPlateEditor` and `Plate` components are imported from `@udecode/plate/react`, not from this package.
67

68
## Architecture
69

70
The @udecode/plate-kbd package follows Plate's standard plugin architecture with two main components:
71

72
- **BaseKbdPlugin**: Core plugin implementation providing fundamental keyboard input formatting capabilities
73
- **KbdPlugin**: React-enhanced version that extends BaseKbdPlugin with React-specific features and optimizations
74
- **Leaf Node Type**: Implements keyboard input as inline leaf nodes within the rich-text structure
75
- **HTML Integration**: Bidirectional support for HTML `<kbd>` elements through serialization/deserialization
76

77
## Capabilities
78

79
### Base Keyboard Input Plugin
80

81
Core keyboard input formatting functionality for Plate editors. Provides leaf node support for inline keyboard shortcut rendering.
82

83
```typescript { .api }
84
/**
85
 * Base plugin for keyboard input formatting support.
86
 * Enables inline keyboard shortcut rendering as leaf nodes.
87
 */
88
const BaseKbdPlugin: PlatePlugin;
89
```
90

91
The BaseKbdPlugin is configured with:
92
- **Key**: `'kbd'` (from KEYS.kbd constant)
93
- **Node Type**: Leaf node (`isLeaf: true`)
94
- **HTML Parsing**: Supports `<KBD>` element deserialization
95
- **HTML Serialization**: Serializes to `<kbd>` elements
96

97
### React Keyboard Input Plugin
98

99
React-enhanced version of the base plugin with additional React-specific features and optimizations.
100

101
```typescript { .api }
102
/**
103
 * React-enhanced keyboard input plugin.
104
 * Extends BaseKbdPlugin with React-specific features.
105
 */
106
const KbdPlugin: PlatePlugin;
107
```
108

109
This plugin is created by wrapping BaseKbdPlugin with `toPlatePlugin()`, providing:
110
- React component integration
111
- Optimized rendering for React environments
112
- Enhanced performance in React applications
113

114
## Usage Examples
115

116
### Basic Keyboard Shortcut Formatting
117

118
```typescript
119
import { createPlateEditor } from "@udecode/plate/react";
120
import { KbdPlugin } from "@udecode/plate-kbd/react";
121

122
// Create editor with kbd support
123
const editor = createPlateEditor({
124
  plugins: [KbdPlugin],
125
});
126

127
// The plugin will automatically render keyboard shortcuts
128
// when they are marked with the kbd formatting
129
```
130

131
### HTML Integration
132

133
```typescript
134
// The plugin automatically handles HTML kbd elements
135
const htmlContent = `
136
  <p>Use <kbd>Ctrl+S</kbd> to save your document.</p>
137
`;
138

139
// This HTML will be properly deserialized with kbd formatting preserved
140
```
141

142
### Programmatic Usage
143

144
```typescript
145
import { KEYS } from "@udecode/plate";
146

147
// The kbd plugin provides the KEYS.kbd constant for identification
148
const kbdKey = KEYS.kbd; // 'kbd'
149

150
// Mark manipulation requires the core Plate editor transforms
151
// These are not provided by this package but by @udecode/plate
152
const editor = useEditorRef();
153
editor.tf.toggleMark(KEYS.kbd);
154

155
// Check if current selection has kbd formatting
156
const isKbdActive = editor.tf.isMark(KEYS.kbd);
157
```
158

159
**Note**: Transform methods (`editor.tf.toggleMark`, `editor.tf.isMark`) are provided by the core Plate framework, not by this package.
160

161
## Types
162

163
```typescript { .api }
164
/**
165
 * Keyboard input text type.
166
 * Text node with kbd formatting mark.
167
 */
168
type TKbdElement = TText & { kbd: true };
169

170
/**
171
 * Plugin configuration type.
172
 * Standard Plate plugin interface.
173
 */
174
interface PlatePlugin {
175
  key: string;
176
  node?: {
177
    isLeaf?: boolean;
178
  };
179
  parsers?: {
180
    html?: {
181
      deserializer?: {
182
        rules?: Array<{ validNodeName: string[] }>;
183
      };
184
    };
185
  };
186
  render?: {
187
    as?: string;
188
  };
189
}
190

191
/**
192
 * Base text node type (from @udecode/slate).
193
 */
194
interface TText {
195
  text: string;
196
  [key: string]: unknown;
197
}
198
```
199

200
## Integration Notes
201

202
### Plugin Dependencies
203

204
- **Required**: `@udecode/plate` (peer dependency >=49.0.0)  
205
- **React Usage**: `react` (>=18.0.0), `react-dom` (>=18.0.0)
206

207
### Compatible Features
208

209
The kbd plugin works seamlessly with other Plate features:
210
- **HTML Serialization**: Automatic conversion to/from HTML `<kbd>` elements
211
- **Markdown Support**: Integration with markdown parsing for kbd syntax
212
- **Autoformatting**: Can be used with Plate's autoformatting capabilities
213
- **Theme Support**: Inherits styling from Plate's theming system
214

215
### Usage Patterns
216

217
Common use cases for the kbd plugin:
218
- **Technical Documentation**: Display keyboard shortcuts in help content
219
- **Tutorial Content**: Show step-by-step key combinations  
220
- **UI Instructions**: Indicate keyboard navigation and shortcuts
221
- **Reference Material**: Document hotkeys and keyboard commands
222

223
## Error Handling
224

225
The plugin follows Plate's standard error handling patterns. No specific exceptions are thrown by the kbd plugin itself, but standard Plate editor errors may occur during:
226
- Plugin registration conflicts
227
- Invalid node structure operations
228
- HTML parsing errors with malformed kbd elements
229

230
For troubleshooting, ensure:
231
- Plugin is properly registered before editor initialization
232
- HTML content contains valid `<kbd>` elements when deserializing
233
- Required peer dependencies are installed at compatible versions