Link

Link Element Link Floating Toolbar Link Toolbar Button

components/demo.tsx

'use client';

import React from 'react';

import { Plate } from '@udecode/plate/react';

import { editorPlugins } from '@/components/editor/plugins/editor-plugins';
import { useCreateEditor } from '@/components/editor/use-create-editor';
import { Editor, EditorContainer } from '@/components/plate-ui/editor';

import { DEMO_VALUES } from './values/demo-values';

export default function Demo({ id }: { id: string }) {
  const editor = useCreateEditor({
    plugins: [...editorPlugins],
    value: DEMO_VALUES[id],
  });

  return (
    <Plate editor={editor}>
      <EditorContainer variant="demo">
        <Editor />
      </EditorContainer>
    </Plate>
  );
}

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

Key	Description
`Cmd + K`	Add a link on the selected text.

Plugin Transforms

`editor.tf.insert.link`

Inserts a link node into the editor.

Parameters

Collapse all

Options for inserting the link.

OptionsInsertLinkOptions

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.

ReturnsReact.AnchorHTMLAttributes<HTMLAnchorElement>

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.

Returnsboolean

Returns true if the link was inserted successfully.

Plugins

`LinkPlugin`

Plugin for link formatting.

Optionsobject

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

Options for creating link node.

Additional options for node insertion.

`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.

Returnsboolean

Returns true if the link was inserted.

`triggerFloatingLink`

Triggers the floating link.

Optionsobject

Collapse all

Whether the floating link should be focused.

`triggerFloatingLinkEdit`

Triggers the floating link edit.

Returnsboolean

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

OptionsTriggerFloatingLinkOptions

Collapse all

Whether the floating link should be focused.

Returnsboolean

Returns true if the link was inserted.

`unwrapLink`

Unwraps a link node.

OptionsUnwrapLinkOptions

Collapse all

If true, split the nodes if the selection is inside the link.

`upsertLink`

Insert or update a link node. The behavior depends on the current selection and options:

If selection is in a link or not a URL:
- With insertTextInLink: true, inserts URL as text in link
- Otherwise, if text is empty, sets it to URL
- Validates URL unless skipValidation: true
If selection is expanded or update: true in a link:
- Removes link node and gets link text
Then:
- Inserts link node with updated URL and target
- If text is provided, replaces link text

Parameters

Collapse all

Options for upserting the link.

OptionsUpsertLinkOptions

Collapse all

The URL of the link.

The text content of the link.

The target attribute of the link.

If true, insert the URL as text in the link.

The options for inserting nodes.

If true, skips URL validation.

Default: false

Returnsboolean

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.

OptionsUpsertLinkTextOptions

Collapse all

The new text to replace the link children with.

`validateUrl`

Validates a URL based on the plugin options.

OptionsValidateUrlOptions

Collapse all

The URL to validate.

Returnsboolean

Returns true if the URL is valid.

`wrapLink`

Wrap a link node with split.

OptionsWrapLinkOptions

Collapse all

The URL of the link.

The target attribute of the link.

`CreateLinkNodeOptions`

Options for creating a new link node.

Optionsobject

Collapse all

The URL of the link node that is being created.

The text that is displayed for the link node. If not provided, the URL is used as the display text.

Specifies where to open the URL:

_blank: new tab
_self: same frame
_parent: parent frame
_top: full window

An array of text nodes that represent the link content.

API Components

`FloatingLinkNewTabInput`

The input component for controlling whether a link opens in a new tab.

State

Collapse all

Whether the link should open in a new tab.

Function to update the checked state.

Reference to the input element.

`FloatingLinkUrlInput`

The input component for entering and editing link URLs.

State

Collapse all

Reference to the input element.

`LinkOpenButton`

The button component for opening the link URL.

State

Collapse all

The link element containing the URL to open.

`useFloatingLinkEdit`

The behavior hook for the floating link edit functionality.

State

Collapse all

The virtual floating returned object.

Returnsobject

Collapse all

The ref callback for the floating element.

Props for the floating element.

Props for the edit button.

Props for the unlink button.

`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.

Returnsobject

Collapse all

The ref callback for the floating element.

Props for the floating element.

Props for the text input.

`useFloatingLinkStore`

The store for managing floating link state.

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.

OptionsUseLinkOptions

Collapse all

The link element.

Returnsobject

Collapse all

Props for the link element.

`useLinkToolbarButton`

The behavior hook for the link toolbar button.

State

Collapse all

Whether the selection is in a link.

Returnsobject

Collapse all

Props for the toolbar button.

`useVirtualFloatingLink`

Custom hook for managing virtual floating of a link.

Optionsobject

Collapse all

The ID of the editor to which the link belongs.

Options for virtual floating.

ReturnsUseVirtualFloatingReturn

The return value of the useVirtualFloating hook.

Link

Features

Installation

Usage

Keyboard Shortcuts

Plugin Transforms

editor.tf.insert.link

Parameters

options object

options object

OptionsInsertLinkOptions

createLinkNodeOptions CreateLinkNodeOptions

createLinkNodeOptions CreateLinkNodeOptions

insertOptions optional InsertNodesOptions

insertOptions optional InsertNodesOptions

Plugin API

editor.api.floatingLink.hide

editor.api.floatingLink.reset

editor.api.floatingLink.show

Parameters

mode FloatingLinkMode

mode FloatingLinkMode

editorId string

editorId string

editor.api.link.getAttributes

Parameters

element TLinkElement

element TLinkElement

ReturnsReact.AnchorHTMLAttributes<HTMLAnchorElement>

editor.api.link.submitFloatingLink

Returnsboolean

Plugins

LinkPlugin

Optionsobject

forceSubmit optional boolean

forceSubmit optional boolean

rangeBeforeOptions optional RangeBeforeOptions

rangeBeforeOptions optional RangeBeforeOptions

triggerFloatingLinkHotkeys optional string | string[]

triggerFloatingLinkHotkeys optional string | string[]

allowedSchemes optional string[]

allowedSchemes optional string[]

dangerouslySkipSanitization optional boolean

dangerouslySkipSanitization optional boolean

defaultLinkAttributes optional AnchorHTMLAttributes<HTMLAnchorElement>

defaultLinkAttributes optional AnchorHTMLAttributes<HTMLAnchorElement>

keepSelectedTextOnPaste optional boolean

keepSelectedTextOnPaste optional boolean

isUrl optional (text: string) => boolean

isUrl optional (text: string) => boolean

getUrlHref optional (url: string) => string | undefined

getUrlHref optional (url: string) => string | undefined

transformInput optional (url: string | null) => string | undefined

transformInput optional (url: string | null) => string | undefined

getLinkUrl optional (prevUrl: string | null) => Promise<string | null>

getLinkUrl optional (prevUrl: string | null) => Promise<string | null>

API

insertLink

Parameters

createLinkNodeOptions CreateLinkNodeOptions

createLinkNodeOptions CreateLinkNodeOptions

options optional InsertNodesOptions

options optional InsertNodesOptions

submitFloatingLink

Returnsboolean

triggerFloatingLink

Optionsobject

focused optional boolean

focused optional boolean

triggerFloatingLinkEdit

Returnsboolean

triggerFloatingLinkInsert

OptionsTriggerFloatingLinkOptions

focused optional boolean

focused optional boolean

Returnsboolean

unwrapLink

OptionsUnwrapLinkOptions

split optional boolean

split optional boolean

`editor.tf.insert.link`

`editor.api.floatingLink.hide`

`editor.api.floatingLink.reset`

`editor.api.floatingLink.show`

`editor.api.link.getAttributes`

`editor.api.link.submitFloatingLink`

`LinkPlugin`

`insertLink`

`submitFloatingLink`

`triggerFloatingLink`

`triggerFloatingLinkEdit`

`triggerFloatingLinkInsert`

`unwrapLink`

`upsertLink`

`upsertLinkText`

`validateUrl`

`wrapLink`

`CreateLinkNodeOptions`

`FloatingLinkNewTabInput`

`FloatingLinkUrlInput`

`LinkOpenButton`

`useFloatingLinkEdit`