Docs
Link

Link

Insert and manage hyperlinks.

Link ElementLink Floating ToolbarLink Toolbar Button

Features

  • Support for hyperlink insertion, edition and removal.

Installation

npm install @udecode/plate-link

Usage

import { LinkPlugin } from '@udecode/plate-link/react';
 
const plugins = [
  // ...otherPlugins,
  LinkPlugin.configure({
    render: { afterEditable: () => <LinkFloatingToolbar /> },
  }),
];

Keyboard Shortcuts

KeyDescription
Cmd + KAdd a link on the selected text.

Plugin Transforms

editor.insert.link

Inserts a link node into the editor.

Parameters

Collapse all

    Options for creating the link node.

    Additional options for inserting nodes.

Plugin API

editor.api.floatingLink.hide

Hides the floating link and resets its state.

editor.api.floatingLink.reset

Resets the floating link state without changing the openEditorId.

editor.api.floatingLink.show

Shows the floating link for the specified mode and editor ID.

Parameters

Collapse all

    The mode to set for the floating link ('edit' or 'insert').

    The ID of the editor where the floating link should be shown.

editor.api.link.getAttributes

Gets the attributes for a link element.

Parameters

Collapse all

    The link element for which to get attributes.

Returns

Collapse all

    The HTML attributes for the link element.

editor.api.link.submitFloatingLink

Inserts a link if the URL is valid, closes the floating link, and focuses the editor.

Returns

Collapse all

    Returns true if the link was inserted successfully.

Plugins

LinkPlugin

Options

Collapse all

    Determines whether to force the submission of the link form.

    Allows custom configurations for rangeBeforeOptions.

    • Default:
    {
  matchString: ' ',
  skipInvalid: true,
  afterMatch: true,
}

    Hotkeys to trigger floating link.

    • Default: 'meta+k, ctrl+k'

    List of allowed URL schemes.

    • Default: ['http', 'https', 'mailto', 'tel']

    Determines whether the sanitation of links should be skipped.

    • Default: false

    Default HTML attributes for link elements.

    • Default: {}

    Keeps selected text on pasting links by default.

    • Default: true

    Callback function to validate a URL.

    • Default: isUrl

    Callback function to optionally get the href for a URL. It returns an optional link that is different from the text content. For example, returns https://google.com for google.com.

    Callback function to optionally transform the submitted URL provided by the user to the URL input before validation.

    On keyboard shortcut or toolbar mousedown, this function is called to get the link URL. The default behavior is to use the browser's native prompt.

API

insertLink

Inserts a link node into the editor.

Parameters

Collapse all

    The editor instance.

submitFloatingLink

Inserts a link if the URL is valid, closes the floating link, and focuses the editor.

  • Insert link if url is valid.
  • Text is url if empty.
  • Close floating link.
  • Focus editor.

Parameters

Collapse all

    The editor instance.

Returns

Collapse all

    Returns true if the link was inserted.

triggerFloatingLink

Triggers the floating link.

Parameters

Collapse all

    The editor instance.

triggerFloatingLinkEdit

Triggers the floating link edit.

Parameters

Collapse all

    The editor instance.

Returns

Collapse all

    Returns true if the link was edited.

triggerFloatingLinkInsert

Trigger floating link.

Do not trigger when:

  • Selection is across blocks.
  • Selection has more than one leaf node.
  • Lowest selection is not text.
  • Selection has a link node.

Parameters

Collapse all

    The editor instance.

Returns

Collapse all

    Returns true if the link was inserted.

unwrapLink

Unwraps a link node.

Parameters

Collapse all

    The editor instance.

upsertLink

If the selection is in a link or the selection is not a URL:

  • If insertTextInLink is true, insert the url as text in the link and exit.
  • Otherwise, if the text is defined and empty, set it to the url.
  • If skipValidation is false (default), validate the url using the validateUrl function. If the validation fails, exit.

If the selection is expanded or the update option is set to true in a link:

  • Remove the link node and get the link text.

Then:

  • Insert the link node with the updated url and target.
  • If text is defined and not empty, replace the link text with the new text.

Parameters

Collapse all

    The editor instance.

Returns

Collapse all

    Returns true if the link was inserted or updated.

upsertLinkText

If the text is different from the link above text, replaces the link children with a new text node. The new text node has the same marks as the first text node in the link.

Parameters

Collapse all

    The editor instance.

validateUrl

Validates a URL based on the plugin options.

Parameters

Collapse all

    The editor instance.

    The URL to validate.

Returns

Collapse all

    Returns true if the URL is valid.

wrapLink

Wrap a link node with split.

Parameters

Collapse all

    The editor instance.

CreateLinkNodeOptions

Attributes

Collapse all

    The URL of the link node that is being created.

    The text that is displayed for the link node. This text is what users see and click on. If not provided, the URL is used as the display text.

    Specifies where to open the URL. This can be _blank for a new tab, _self for the same frame, _parent for the parent frame, or _top for the full body of the window.

    An array of TText objects that represent the child nodes of the link node. These child nodes are displayed as the contents of the link node.

API Components

FloatingLinkNewTabInput

The input for the link new tab.

State

Collapse all

    Whether the link should open in a new tab.

    The ref of the input element.

    Sets the checked state.

FloatingLinkUrlInput

The input for the link URL.

State

Collapse all

    The ref of the input element.

LinkOpenButton

The button to open the link.

State

Collapse all

    The link element to open.

useFloatingLinkEdit

The behavior hook for the floating link edit.

State

Collapse all

    The virtual floating returned object.

Returns

Collapse all

useFloatingLinkEnter

Listens for the Enter key press event and submits the floating link in the editor.

useFloatingLinkEscape

Listens for the Escape key press event and handles the behavior of the floating link in the editor.

useFloatingLinkInsert

The behavior hook for inserting a link.

State

Collapse all

    The virtual floating returned object.

    The ref of the floating element.

Returns

Collapse all

    The ref of the floating element.

    Props

    Collapse all

useFloatingLinkStore

The store for the floating link.

State

Collapse all

    The ID of the editor that has the floating link.

    Whether the mouse is down.

    Whether the floating link has been updated.

    The URL of the floating link.

    The text of the floating link.

    Whether the floating link should open in a new tab.

    The mode of the floating link.

    Whether the floating link is being edited.

useLink

The behavior hook for the link element.

Parameters

Collapse all

Returns

Collapse all

useLinkToolbarButton

The behavior hook for the link toolbar button.

State

Collapse all

    Whether the selection is in a link.

Returns

Collapse all

useVirtualFloatingLink

Custom hook for managing virtual floating of a link.

Parameters

Collapse all

    The ID of the editor to which the link belongs.

    Options for virtual floating.

Returns

Collapse all

    The return value of the useVirtualFloating hook.

Line HeightList