CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-udecode--plate-alignment

Text alignment plugin for Plate rich-text editor framework

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

Plate Alignment

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.

Package Information

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

Core Imports

import { BaseTextAlignPlugin, setAlign, type Alignment } from "@udecode/plate-alignment";

For React functionality:

import { TextAlignPlugin } from "@udecode/plate-alignment/react";

CommonJS:

const { BaseTextAlignPlugin, setAlign } = require("@udecode/plate-alignment");
const { TextAlignPlugin } = require("@udecode/plate-alignment/react");

Basic Usage

import { createPlateEditor } from "@udecode/plate";
import { BaseTextAlignPlugin, setAlign } from "@udecode/plate-alignment";

// Create editor with alignment plugin
const editor = createPlateEditor({
  plugins: [
    BaseTextAlignPlugin.configure({
      // Plugin configuration options
    }),
  ],
});

// Programmatically set alignment
setAlign(editor, "center");
setAlign(editor, "right");
setAlign(editor, "justify");

For React applications:

import { Plate } from "@udecode/plate/react";
import { TextAlignPlugin } from "@udecode/plate-alignment/react";

function MyEditor() {
  return (
    <Plate
      plugins={[
        TextAlignPlugin.configure({
          // Plugin configuration options
        }),
      ]}
    >
      {/* Editor components */}
    </Plate>
  );
}

Architecture

The package is structured around the Plate plugin architecture:

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

Capabilities

Base Text Alignment Plugin

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

/**
 * Creates a plugin that adds alignment functionality to the editor.
 * Provides HTML parsing, node property management, and transform integration.
 */
const BaseTextAlignPlugin: SlatePlugin;

Plugin Configuration:

The plugin is created with these specific configuration options:

BaseTextAlignPlugin = createSlatePlugin({
  key: KEYS.textAlign,
  inject: {
    isBlock: true,
    nodeProps: {
      defaultNodeValue: 'start',
      nodeKey: 'align',
      styleKey: 'textAlign',
      validNodeValues: ['start', 'left', 'center', 'right', 'end', 'justify'],
    },
    targetPlugins: [KEYS.p],
  },
});
  • Key: Uses KEYS.textAlign from Plate
  • Default Value: 'start' - when set to default, the property is removed
  • Valid Values: ['start', 'left', 'center', 'right', 'end', 'justify']
  • Target Plugins: Applies to paragraph plugins (KEYS.p) by default
  • Node Property: Stores alignment in align property on editor nodes
  • Style Mapping: Maps to CSS textAlign property during HTML parsing

HTML Deserialization: Automatically parses textAlign CSS styles from HTML elements during editor initialization.

Extended Transforms:

  • set: Transform function for setting alignment (bound to setAlign)

Set Alignment Transform

Programmatically sets text alignment on editor nodes.

/**
 * Transform function to set text alignment on editor nodes
 * @param editor - The Slate editor instance
 * @param value - The alignment value to set
 * @param setNodesOptions - Optional configuration for setNodes operation
 */
function setAlign(
  editor: SlateEditor,
  value: Alignment,
  setNodesOptions?: SetNodesOptions
): void;

Behavior:

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

Usage Example:

import { setAlign } from "@udecode/plate-alignment";
import { useEditorRef } from "@udecode/plate/react";

function AlignmentControls() {
  const editor = useEditorRef();

  const handleAlign = (alignment: Alignment) => {
    setAlign(editor, alignment);
  };

  return (
    <div>
      <button onClick={() => handleAlign("left")}>Left</button>
      <button onClick={() => handleAlign("center")}>Center</button>
      <button onClick={() => handleAlign("right")}>Right</button>
      <button onClick={() => handleAlign("justify")}>Justify</button>
    </div>
  );
}

React Text Alignment Plugin

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

/**
 * React-compatible text alignment plugin
 * Wraps BaseTextAlignPlugin with React-specific functionality
 */
const TextAlignPlugin: PlatePlugin;

Usage in React Editor:

import { useEditorRef } from "@udecode/plate/react";
import { TextAlignPlugin, setAlign } from "@udecode/plate-alignment/react";

function AlignmentToolbar() {
  const editor = useEditorRef();

  const handleAlign = (value: Alignment) => {
    setAlign(editor, value);
    // Focus editor after setting alignment
    editor.tf.focus();
  };

  return (
    <div>
      <button onClick={() => handleAlign("left")}>Align Left</button>
      <button onClick={() => handleAlign("center")}>Align Center</button>
      <button onClick={() => handleAlign("right")}>Align Right</button>
      <button onClick={() => handleAlign("justify")}>Justify</button>
    </div>
  );
}

Types

/**
 * Union type defining valid text alignment values
 */
type Alignment = 'center' | 'end' | 'justify' | 'left' | 'right' | 'start';

/**
 * Core Slate editor interface extended with Plate functionality
 * Includes plugin management, transforms, and API methods
 */
interface SlateEditor extends BaseEditor {
  api: EditorApi & UnionToIntersection<InferApi<CorePlugin>>;
  tf: EditorTransforms & UnionToIntersection<InferTransforms<CorePlugin>>;
  transforms: EditorTransforms & UnionToIntersection<InferTransforms<CorePlugin>>;
  plugins: Record<string, AnyEditorPlugin>;
  getPlugin<C extends AnyPluginConfig>(plugin: WithRequiredKey<C>): EditorPlugin<C>;
  // ... additional Plate-specific methods
}

/**
 * Options for setNodes operations supporting query matching and node targeting
 */
interface SetNodesOptions<V extends Value = Value> {
  /** Match specific nodes using predicates */
  match?: Predicate<NodeIn<V>>;
  /** Comparison function for property updates */
  compare?: PropsCompare;
  /** Merge function for combining properties */
  merge?: PropsMerge;
  /** Whether to split text nodes */
  split?: boolean;
  /** Apply only to text nodes in non-void nodes */
  marks?: boolean;
  /** Match by node ID */
  id?: boolean | string;
  /** Match block nodes only */
  block?: boolean;
  // ... additional query options
}

/**
 * Core headless plugin interface for Slate functionality
 */
interface SlatePlugin<C extends AnyPluginConfig = PluginConfig> extends BasePlugin<C> {
  /** Unique plugin identifier */
  key: C['key'];
  /** Extend editor with custom functionality */
  extendEditor?: ExtendEditor<WithAnyKey<C>>;
  /** Plugin injection configuration */
  inject: {
    nodeProps?: InjectNodeProps<WithAnyKey<C>>;
    targetPlugins?: string[];
    // ... additional injection options
  };
  /** Parser configuration for HTML/markdown */
  parsers: { /* parser configuration */ };
  // ... additional plugin properties
}

/**
 * React-compatible plugin interface extending SlatePlugin with React features
 */
interface PlatePlugin<C extends AnyPluginConfig = PluginConfig> extends SlatePlugin<C> {
  /** React hooks for component lifecycle */
  useHooks?: UseHooks<WithAnyKey<C>>;
  /** DOM event handlers */
  handlers: DOMHandlers<WithAnyKey<C>> & {
    onChange?: OnChange<WithAnyKey<C>>;
  };
  /** React component rendering */
  render: { /* render configuration */ };
  // ... additional React-specific properties
}
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@udecode/plate-alignment@49.0.x
Publish Source
CLI
Badge
tessl/npm-udecode--plate-alignment badge