or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-plugin.mdfloating-interface.mdindex.mdreact-components.mdreact-integration.mdtransforms.mdurl-utils.md
tile.json

tessl/npm-udecode--plate-link

Link plugin for Plate rich text editor providing hyperlink functionality with URL validation, keyboard shortcuts, and UI components

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@udecode/plate-link@49.0.x

To install, run

npx @tessl/cli install tessl/npm-udecode--plate-link@49.0.0

index.mddocs/

Plate Link Plugin

The Plate Link Plugin provides comprehensive hyperlink functionality for the Plate rich text editor framework. It enables users to insert, edit, and manage hyperlinks within rich text content with advanced features including URL validation, automatic link detection, keyboard shortcuts, and floating UI components.

Package Information

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

Core Imports

import { BaseLinkPlugin } from "@udecode/plate-link";
import { LinkPlugin } from "@udecode/plate-link/react";

For individual utilities and transforms:

import { 
  upsertLink, 
  validateUrl, 
  encodeUrlIfNeeded 
} from "@udecode/plate-link";

For React components and hooks:

import { 
  useLink, 
  useLinkToolbarButton, 
  FloatingLinkUrlInput 
} from "@udecode/plate-link/react";

Basic Usage

import { createPlateEditor } from "@udecode/plate";
import { BaseLinkPlugin } from "@udecode/plate-link";

// Basic plugin setup
const editor = createPlateEditor({
  plugins: [
    BaseLinkPlugin.configure({
      options: {
        allowedSchemes: ['http', 'https', 'mailto', 'tel'],
        keepSelectedTextOnPaste: true,
        triggerFloatingLinkHotkeys: 'meta+k, ctrl+k'
      }
    })
  ]
});

// Insert a link programmatically
import { insertLink } from "@udecode/plate-link";

insertLink(editor, { 
  url: "https://example.com", 
  text: "Example Link" 
});

Architecture

The Plate Link Plugin is built around several key components:

  • Base Plugin: Core link functionality with editor transforms and validation
  • React Plugin: Enhanced plugin with floating UI, keyboard shortcuts, and React-specific features
  • Transform Functions: Low-level operations for link insertion, modification, and removal
  • Utility Functions: URL processing, validation, and attribute generation
  • React Components: Pre-built UI components and hooks for link editing interfaces
  • Floating UI System: Modal-style link editing with positioning and keyboard handling

Capabilities

Core Link Plugin

Foundation plugin providing basic link functionality, HTML serialization, and editor integration.

const BaseLinkPlugin: PlatePlugin<BaseLinkConfig>;

type BaseLinkConfig = PluginConfig<'a', {
  allowedSchemes?: string[];
  dangerouslySkipSanitization?: boolean;
  defaultLinkAttributes?: React.AnchorHTMLAttributes<HTMLAnchorElement>;
  forceSubmit?: boolean;
  keepSelectedTextOnPaste?: boolean;
  rangeBeforeOptions?: EditorBeforeOptions;
  triggerFloatingLinkHotkeys?: string[] | string;
  getLinkUrl?: (prevUrl: string | null) => Promise<string | null>;
  getUrlHref?: (url: string) => string | undefined;
  isUrl?: (text: string) => boolean;
  transformInput?: (url: string) => string | undefined;
}>;

Core Plugin

React Integration

React-enhanced plugin with floating UI, state management, and component integration.

const LinkPlugin: PlatePlugin<LinkConfig>;

type LinkConfig = ExtendConfig<BaseLinkConfig, {
  isEditing: boolean;
  mode: FloatingLinkMode;
  mouseDown: boolean;
  newTab: boolean;
  openEditorId: string | null;
  text: string;
  updated: boolean;
  url: string;
  triggerFloatingLinkHotkeys?: string;
}>;

type FloatingLinkMode = '' | 'edit' | 'insert';

React Integration

Link Transforms

Programmatic functions for creating, modifying, and removing links within the editor.

function insertLink(
  editor: SlateEditor, 
  options: CreateLinkNodeOptions, 
  insertOptions?: InsertNodesOptions
): void;

function upsertLink(
  editor: SlateEditor, 
  options: UpsertLinkOptions
): boolean | undefined;

function unwrapLink(
  editor: SlateEditor, 
  options?: { split?: boolean } & UnwrapNodesOptions
): boolean;

Link Transforms

URL Utilities

Utility functions for URL processing, validation, and encoding/decoding.

function validateUrl(editor: SlateEditor, url: string): boolean;
function encodeUrlIfNeeded(url: string): string;
function safeDecodeUrl(url: string): string;
function getLinkAttributes(
  editor: SlateEditor, 
  link: TLinkElement
): React.AnchorHTMLAttributes<HTMLAnchorElement>;

URL Utilities

React Components

Pre-built React components and hooks for building link editing interfaces.

function useLink({ element }: { element: TLinkElement }): {
  props: React.AnchorHTMLAttributes<HTMLAnchorElement>;
};

function useLinkToolbarButton(): {
  props: {
    pressed: boolean;
    onClick: () => void;
    onMouseDown: (e: React.MouseEvent) => void;
  };
};

const FloatingLinkUrlInput: React.FC;
const FloatingLinkNewTabInput: React.FC;

React Components

Floating Link Interface

Complete floating UI system for inserting and editing links with keyboard shortcuts and positioning.

function triggerFloatingLink(
  editor: SlateEditor, 
  options?: { focused?: boolean }
): void;

function useFloatingLinkInsert(state: LinkFloatingToolbarState): {
  hidden: boolean;
  props: object;
  ref: RefObject;
  textInputProps: object;
};

function useFloatingLinkEdit(state: LinkFloatingToolbarState): {
  editButtonProps: object;
  props: object;
  ref: RefObject;
  unlinkButtonProps: object;
};

Floating Interface

Types

// Core types (imported from @udecode/plate)
type TLinkElement = {
  type: 'a';
  url: string;
  target?: string;
  children: TText[];
}

interface CreateLinkNodeOptions {
  url: string;
  children?: TText[];
  target?: string;
  text?: string;
}

interface UpsertLinkOptions extends CreateLinkNodeOptions {
  insertNodesOptions?: InsertNodesOptions;
  insertTextInLink?: boolean;
  skipValidation?: boolean;
  unwrapNodesOptions?: UnwrapNodesOptions;
  wrapNodesOptions?: WrapNodesOptions;
}

interface LinkFloatingToolbarState {
  floatingOptions?: UseVirtualFloatingOptions;
}