tessl/npm-udecode--plate-link
Link plugin for Plate rich text editor providing hyperlink functionality with URL validation, keyboard shortcuts, and UI components
—
Pending
transforms.mddocs/
Link Transforms
Transform functions provide programmatic control over link creation, modification, and removal within Plate editors. These low-level operations power the plugin's automatic behaviors and can be used directly for custom link handling.
Capabilities
Link Insertion
insertLink
Inserts a new link node at the current selection or specified location.
/**
* Insert a link node at the current selection
* @param editor - Slate editor instance
* @param options - Link creation options
* @param insertOptions - Node insertion options
*/
function insertLink(
editor: SlateEditor,
options: CreateLinkNodeOptions,
insertOptions?: InsertNodesOptions
): void;
interface CreateLinkNodeOptions {
/** The URL for the link */
url: string;
/** Child text nodes (optional) */
children?: TText[];
/** Link target attribute (e.g., '_blank') */
target?: string;
/** Text content for the link */
text?: string;
}Usage Examples:
import { insertLink } from "@udecode/plate-link";
// Insert basic link
insertLink(editor, {
url: "https://example.com",
text: "Example"
});
// Insert link with target
insertLink(editor, {
url: "https://external.com",
text: "External Link",
target: "_blank"
});
// Insert at specific location
insertLink(editor, {
url: "https://example.com",
text: "Link"
}, {
at: [0, 1] // Specific path
});Smart Link Operations
upsertLink
Intelligently inserts or updates links based on current selection context. Handles both creating new links and updating existing ones.
/**
* Insert or update a link based on current selection context
* @param editor - Slate editor instance
* @param options - Comprehensive link options
* @returns Whether the operation was successful
*/
function upsertLink(
editor: SlateEditor,
options: UpsertLinkOptions
): boolean | undefined;
interface UpsertLinkOptions extends CreateLinkNodeOptions {
/** Options for node insertion */
insertNodesOptions?: InsertNodesOptions;
/** Whether to insert text inside existing link */
insertTextInLink?: boolean;
/** Skip URL validation step */
skipValidation?: boolean;
/** Options for node unwrapping */
unwrapNodesOptions?: UnwrapNodesOptions;
/** Options for node wrapping */
wrapNodesOptions?: WrapNodesOptions;
}Usage Examples:
import { upsertLink } from "@udecode/plate-link";
// Smart link insertion/update
const success = upsertLink(editor, {
url: "https://example.com",
text: "Example Link"
});
// Update existing link with validation skip
upsertLink(editor, {
url: "https://newurl.com",
skipValidation: true,
insertTextInLink: true
});
// Handle selection-based link creation
if (editor.selection) {
upsertLink(editor, {
url: "https://example.com"
// Will use selected text if available
});
}upsertLinkText
Updates the text content of a link while preserving link formatting and attributes.
/**
* Update the text content of a link element
* @param editor - Slate editor instance
* @param options - Text update options
*/
function upsertLinkText(
editor: SlateEditor,
options: UpsertLinkOptions
): void;Usage Examples:
import { upsertLinkText } from "@udecode/plate-link";
// Update link text content
upsertLinkText(editor, {
text: "New Link Text",
url: "https://example.com"
});Link Wrapping
wrapLink
Wraps the current selection or specified nodes in a link element.
/**
* Wrap selected nodes in a link element
* @param editor - Slate editor instance
* @param options - Wrapping options with URL and target
*/
function wrapLink(
editor: SlateEditor,
options: WrapLinkOptions
): void;
interface WrapLinkOptions extends WrapNodesOptions {
/** The URL for the link */
url: string;
/** Optional target attribute */
target?: string;
}Usage Examples:
import { wrapLink } from "@udecode/plate-link";
// Wrap selection in link
wrapLink(editor, {
url: "https://example.com"
});
// Wrap with target attribute
wrapLink(editor, {
url: "https://external.com",
target: "_blank"
});
// Wrap specific nodes
wrapLink(editor, {
url: "https://example.com",
at: editor.selection
});Link Removal
unwrapLink
Removes link formatting from nodes while preserving text content.
/**
* Remove link formatting from nodes
* @param editor - Slate editor instance
* @param options - Unwrapping options
* @returns Whether any links were unwrapped
*/
function unwrapLink(
editor: SlateEditor,
options?: { split?: boolean } & UnwrapNodesOptions
): boolean;Usage Examples:
import { unwrapLink } from "@udecode/plate-link";
// Remove link from selection
const removed = unwrapLink(editor);
// Remove with splitting behavior
unwrapLink(editor, { split: true });
// Remove from specific location
unwrapLink(editor, {
at: [0, 1, 0]
});React-Specific Transforms
submitFloatingLink
Processes floating link form submission, validates the URL, and inserts or updates the link.
/**
* Process floating link form submission
* @param editor - Slate editor instance
* @returns Whether the submission was successful
*/
function submitFloatingLink(
editor: SlateEditor
): boolean | undefined;Usage Examples:
import { submitFloatingLink } from "@udecode/plate-link/react";
// Handle form submission
const handleSubmit = () => {
const success = submitFloatingLink(editor);
if (success) {
console.log("Link submitted successfully");
}
};Advanced Transform Patterns
Conditional Link Operations
import { upsertLink, unwrapLink } from "@udecode/plate-link";
// Toggle link behavior
function toggleLink(editor: SlateEditor, url: string) {
const hasLink = editor.api.some({
match: { type: 'a' }
});
if (hasLink) {
unwrapLink(editor);
} else {
upsertLink(editor, { url });
}
}Batch Link Operations
import { insertLink } from "@udecode/plate-link";
// Insert multiple links
function insertMultipleLinks(editor: SlateEditor, links: Array<{url: string, text: string}>) {
editor.tf.withoutNormalizing(() => {
links.forEach((link, index) => {
insertLink(editor, link, {
at: [index]
});
});
});
}Link Validation and Transformation
import { upsertLink, validateUrl } from "@udecode/plate-link";
// Insert with validation
function insertValidatedLink(editor: SlateEditor, url: string, text: string) {
if (validateUrl(editor, url)) {
return upsertLink(editor, { url, text });
}
throw new Error('Invalid URL');
}Install with Tessl CLI
npx tessl i tessl/npm-udecode--plate-link