Plate Keyboard Input Plugin

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.

Package Information

• Package Name: @udecode/plate-kbd
• Package Type: npm
• Language: TypeScript
• Installation: npm install @udecode/plate-kbd

Core Imports

import { BaseKbdPlugin } from "@udecode/plate-kbd";

// For React-specific usage
import { KbdPlugin } from "@udecode/plate-kbd/react";

CommonJS:

const { BaseKbdPlugin } = require("@udecode/plate-kbd");

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

Package Exports

The package provides dual export structure:

• Main entry (@udecode/plate-kbd): Core plugin without React dependencies
• React entry (@udecode/plate-kbd/react): React-enhanced plugin version

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

Basic Usage

// Import dependencies
import { createPlateEditor } from "@udecode/plate/react";
import { Plate } from "@udecode/plate/react";
import { KbdPlugin } from "@udecode/plate-kbd/react";

// Register the plugin with Plate
const editor = createPlateEditor({
  plugins: [
    // ... other plugins
    KbdPlugin,
  ],
});

// Use in JSX
function MyEditor() {
  return (
    <Plate editor={editor}>
      <div>
        Press <kbd>Ctrl+C</kbd> to copy or <kbd>Cmd+V</kbd> to paste.
      </div>
    </Plate>
  );
}

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

Architecture

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

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

Capabilities

Base Keyboard Input Plugin

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

/**
 * Base plugin for keyboard input formatting support.
 * Enables inline keyboard shortcut rendering as leaf nodes.
 */
const BaseKbdPlugin: PlatePlugin;

The BaseKbdPlugin is configured with:

• Key: 'kbd' (from KEYS.kbd constant)
• Node Type: Leaf node (isLeaf: true)
• HTML Parsing: Supports <KBD> element deserialization
• HTML Serialization: Serializes to <kbd> elements

React Keyboard Input Plugin

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

/**
 * React-enhanced keyboard input plugin.
 * Extends BaseKbdPlugin with React-specific features.
 */
const KbdPlugin: PlatePlugin;

This plugin is created by wrapping BaseKbdPlugin with toPlatePlugin(), providing:

• React component integration
• Optimized rendering for React environments
• Enhanced performance in React applications

Usage Examples

Basic Keyboard Shortcut Formatting

import { createPlateEditor } from "@udecode/plate/react";
import { KbdPlugin } from "@udecode/plate-kbd/react";

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

// The plugin will automatically render keyboard shortcuts
// when they are marked with the kbd formatting

HTML Integration

// The plugin automatically handles HTML kbd elements
const htmlContent = `
  <p>Use <kbd>Ctrl+S</kbd> to save your document.</p>
`;

// This HTML will be properly deserialized with kbd formatting preserved

Programmatic Usage

import { KEYS } from "@udecode/plate";

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

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

// Check if current selection has kbd formatting
const isKbdActive = editor.tf.isMark(KEYS.kbd);

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

Types

/**
 * Keyboard input text type.
 * Text node with kbd formatting mark.
 */
type TKbdElement = TText & { kbd: true };

/**
 * Plugin configuration type.
 * Standard Plate plugin interface.
 */
interface PlatePlugin {
  key: string;
  node?: {
    isLeaf?: boolean;
  };
  parsers?: {
    html?: {
      deserializer?: {
        rules?: Array<{ validNodeName: string[] }>;
      };
    };
  };
  render?: {
    as?: string;
  };
}

/**
 * Base text node type (from @udecode/slate).
 */
interface TText {
  text: string;
  [key: string]: unknown;
}

Integration Notes

Plugin Dependencies

• Required: @udecode/plate (peer dependency >=49.0.0)
• React Usage: react (>=18.0.0), react-dom (>=18.0.0)

Compatible Features

The kbd plugin works seamlessly with other Plate features:

• HTML Serialization: Automatic conversion to/from HTML <kbd> elements
• Markdown Support: Integration with markdown parsing for kbd syntax
• Autoformatting: Can be used with Plate's autoformatting capabilities
• Theme Support: Inherits styling from Plate's theming system

Usage Patterns

Common use cases for the kbd plugin:

• Technical Documentation: Display keyboard shortcuts in help content
• Tutorial Content: Show step-by-step key combinations
• UI Instructions: Indicate keyboard navigation and shortcuts
• Reference Material: Document hotkeys and keyboard commands

Error Handling

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:

• Plugin registration conflicts
• Invalid node structure operations
• HTML parsing errors with malformed kbd elements

For troubleshooting, ensure:

• Plugin is properly registered before editor initialization
• HTML content contains valid <kbd> elements when deserializing
• Required peer dependencies are installed at compatible versions