Link

Plus Link Element Link Floating Toolbar Link Toolbar Button

Features

Support for hyperlink insertion, edition and removal.

Kit Usage

Installation

The fastest way to add link functionality is with the LinkKit, which includes pre-configured LinkPlugin with floating toolbar and Plate UI components.

LinkElement: Renders link elements.
LinkFloatingToolbar: Provides floating toolbar for link editing.

Add Kit

Add the kit to your plugins:

import { createPlateEditor } from 'platejs/react';
import { LinkKit } from '@/components/editor/plugins/link-kit';
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...LinkKit,
  ],
});

Manual Usage

Installation


pnpm add @platejs/link

Add Plugin

Include LinkPlugin in your Plate plugins array when creating the editor.

import { LinkPlugin } from '@platejs/link/react';
import { createPlateEditor } from 'platejs/react';
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    LinkPlugin,
  ],
});

Configure Plugin

Configure the plugin with floating toolbar and custom components.

import { LinkPlugin } from '@platejs/link/react';
import { createPlateEditor } from 'platejs/react';
import { LinkElement } from '@/components/ui/link-node';
import { LinkFloatingToolbar } from '@/components/ui/link-toolbar';
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    LinkPlugin.configure({
      render: {
        node: LinkElement,
        afterEditable: () => <LinkFloatingToolbar />,
      },
    }),
  ],
});

render.afterEditable: Renders LinkFloatingToolbar after the editable area for link editing.
render.node: Assigns LinkElement to render link elements.

You can add LinkToolbarButton to your Toolbar to insert and edit links.

Keyboard Shortcuts

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

Plate Plus

Get the code

Plugins

`LinkPlugin`

Plugin for link formatting.

Optionsobject

forceSubmit optional boolean
Determines whether to force the submission of the link form.
rangeBeforeOptions optional RangeBeforeOptions
Allows custom configurations for rangeBeforeOptions.
- Default:
```
{
  matchString: ' ',
  skipInvalid: true,
  afterMatch: true,
}
```
triggerFloatingLinkHotkeys optional string | string[]
Hotkeys to trigger floating link.
- Default: 'meta+k, ctrl+k'
allowedSchemes optional string[]
List of allowed URL schemes.
- Default: ['http', 'https', 'mailto', 'tel']
dangerouslySkipSanitization optional boolean
Determines whether the sanitation of links should be skipped.
- Default: false
defaultLinkAttributes optional AnchorHTMLAttributes<HTMLAnchorElement>
Default HTML attributes for link elements.
- Default: {}
keepSelectedTextOnPaste optional boolean
Keeps selected text on pasting links by default.
- Default: true
isUrl optional (text: string) => boolean
Callback function to validate a URL.
- Default: isUrl
getUrlHref optional (url: string) => string | undefined
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.
transformInput optional (url: string | null) => string | undefined
Callback function to optionally transform the submitted URL provided by the user to the URL input before validation.
getLinkUrl optional (prevUrl: string | null) => Promise<string | null>
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.

Transforms

`tf.insert.link`

Inserts a link node into the editor.

Parameters

Collapse all

options object

Options for inserting the link.

OptionsInsertLinkOptions

Collapse all

createLinkNodeOptions CreateLinkNodeOptions

Options for creating the link node.

insertOptions optional InsertNodesOptions

Additional options for inserting nodes.

API

`api.floatingLink.hide`

Hides the floating link and resets its state.

`api.floatingLink.reset`

Resets the floating link state without changing the openEditorId.

`api.floatingLink.show`

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

Parameters

Collapse all

mode FloatingLinkMode

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

editorId string

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

`api.link.getAttributes`

Gets the attributes for a link element.

Parameters

Collapse all

element TLinkElement

The link element for which to get attributes.

ReturnsReact.AnchorHTMLAttributes<HTMLAnchorElement>

The HTML attributes for the link element.

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

`insertLink`

Inserts a link node into the editor.

Parameters

Collapse all

createLinkNodeOptions CreateLinkNodeOptions

Options for creating link node.

options optional InsertNodesOptions

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

focused optional boolean

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

focused optional boolean

Whether the floating link should be focused.

Returnsboolean

Returns true if the link was inserted.

`unwrapLink`

Unwraps a link node.

OptionsUnwrapLinkOptions

Collapse all

split optional boolean

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 UpsertLinkOptions

Options for upserting the link.

OptionsUpsertLinkOptions

Collapse all

url string

The URL of the link.

text optional string

The text content of the link.

target optional string

The target attribute of the link.

insertTextInLink optional boolean

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

insertNodesOptions optional InsertNodesOptions

The options for inserting nodes.

skipValidation optional boolean

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

text optional string

The new text to replace the link children with.

`validateUrl`

Validates a URL based on the plugin options.

OptionsValidateUrlOptions

Collapse all

url string

The URL to validate.

Returnsboolean

Returns true if the URL is valid.

`wrapLink`

Wrap a link node with split.

OptionsWrapLinkOptions

Collapse all

url string

The URL of the link.

target optional string

The target attribute of the link.

`CreateLinkNodeOptions`

Options for creating a new link node.

Optionsobject

Collapse all

url string

The URL of the link node that is being created.

text optional string

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

target optional string

Specifies where to open the URL:

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

children optional TText[]

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

checked boolean

Whether the link should open in a new tab.

setChecked React.Dispatch<React.SetStateAction<boolean>>

Function to update the checked state.

ref RefObject<HTMLInputElement>

Reference to the input element.

`FloatingLinkUrlInput`

The input component for entering and editing link URLs.

State

Collapse all

ref RefObject<HTMLInputElement>

Reference to the input element.

`LinkOpenButton`

The button component for opening the link URL.

State

Collapse all

element TLinkElement

The link element containing the URL to open.

`useFloatingLinkEdit`

The behavior hook for the floating link edit functionality.

State

Collapse all

floating optional object

The virtual floating returned object.

Returnsobject

Collapse all

ref function

The ref callback for the floating element.

props object

Props for the floating element.

editButtonProps object

Props for the edit button.

unlinkButtonProps object

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

floating ReturnType<typeof useFloatingLinkInsertState>

The virtual floating returned object.

refClickOutside React.Ref

The ref of the floating element.

Returnsobject

Collapse all

ref function

The ref callback for the floating element.

props object

Props for the floating element.

textInputProps object

Props for the text input.

`useLink`

The behavior hook for the link element.

OptionsUseLinkOptions

Collapse all

element TLinkElement

The link element.

Returnsobject

Collapse all

props object

Props for the link element.

`useLinkToolbarButton`

The behavior hook for the link toolbar button.

State

Collapse all

pressed boolean

Whether the selection is in a link.

Returnsobject

Collapse all

props object

Props for the toolbar button.

`useVirtualFloatingLink`

Custom hook for managing virtual floating of a link.

Optionsobject

Collapse all

editorId string

The ID of the editor to which the link belongs.

floatingOptions optional UseVirtualFloatingOptions

Options for virtual floating.

ReturnsUseVirtualFloatingReturn

The return value of the useVirtualFloating hook.

链接经典列表

Link

Features

Kit Usage

Installation

Add Kit

Manual Usage

Installation

Add Plugin

Configure Plugin

Add Toolbar Button

Keyboard Shortcuts

Plate Plus

Plugins

LinkPlugin

Optionsobject

forceSubmit optional boolean

rangeBeforeOptions optional RangeBeforeOptions

triggerFloatingLinkHotkeys optional string | string[]

allowedSchemes optional string[]

dangerouslySkipSanitization optional boolean

defaultLinkAttributes optional AnchorHTMLAttributes<HTMLAnchorElement>

keepSelectedTextOnPaste optional boolean

isUrl optional (text: string) => boolean

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

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

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

Transforms

tf.insert.link

Parameters

options object

OptionsInsertLinkOptions

createLinkNodeOptions CreateLinkNodeOptions

insertOptions optional InsertNodesOptions

API

api.floatingLink.hide

api.floatingLink.reset

api.floatingLink.show

Parameters

mode FloatingLinkMode

editorId string

api.link.getAttributes

Parameters

element TLinkElement

ReturnsReact.AnchorHTMLAttributes<HTMLAnchorElement>

api.link.submitFloatingLink

Returnsboolean

insertLink

Parameters

createLinkNodeOptions CreateLinkNodeOptions

options optional InsertNodesOptions

submitFloatingLink

Returnsboolean

triggerFloatingLink

Optionsobject

focused optional boolean

triggerFloatingLinkEdit

Returnsboolean

triggerFloatingLinkInsert

OptionsTriggerFloatingLinkOptions

focused optional boolean

Returnsboolean

unwrapLink

OptionsUnwrapLinkOptions

split optional boolean

upsertLink

Parameters

options UpsertLinkOptions

OptionsUpsertLinkOptions

url string

text optional string

target optional string

insertTextInLink optional boolean

insertNodesOptions optional InsertNodesOptions

skipValidation optional boolean

Returnsboolean

upsertLinkText

OptionsUpsertLinkTextOptions

text optional string

validateUrl

OptionsValidateUrlOptions

`LinkPlugin`

`tf.insert.link`

`api.floatingLink.hide`

`api.floatingLink.reset`

`api.floatingLink.show`

`api.link.getAttributes`

`api.link.submitFloatingLink`

`insertLink`

`submitFloatingLink`

`triggerFloatingLink`

`triggerFloatingLinkEdit`

`triggerFloatingLinkInsert`

`unwrapLink`

`upsertLink`

`upsertLinkText`

`validateUrl`

`wrapLink`

`CreateLinkNodeOptions`

`FloatingLinkNewTabInput`

`FloatingLinkUrlInput`

`LinkOpenButton`

`useFloatingLinkEdit`

`useFloatingLinkEnter`

`useFloatingLinkEscape`

`useFloatingLinkInsert`

`useLink`

`useLinkToolbarButton`

`useVirtualFloatingLink`