Link
Insert and manage hyperlinks.
'use client';
import React from 'react';
import { Plate } from '@udecode/plate-common/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>
);
}
Installation
npm install @udecode/plate-linkUsage
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
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
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
The link element for which to get attributes.
Returns
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
Returns true if the link was inserted successfully.
Plugins
LinkPlugin
Options
- Default:
- Default:
'meta+k, ctrl+k' - Default:
['http', 'https', 'mailto', 'tel'] - Default:
false - Default:
{} - Default:
true - Default:
isUrl
Determines whether to force the submission of the link form.
Allows custom configurations for rangeBeforeOptions.
{
matchString: ' ',
skipInvalid: true,
afterMatch: true,
}Hotkeys to trigger floating link.
List of allowed URL schemes.
Determines whether the sanitation of links should be skipped.
Default HTML attributes for link elements.
Keeps selected text on pasting links by default.
Callback function to validate a URL.
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
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
The editor instance.
Returns
Returns true if the link was inserted.
triggerFloatingLink
Triggers the floating link.
Parameters
The editor instance.
triggerFloatingLinkEdit
Triggers the floating link edit.
Parameters
The editor instance.
Returns
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
The editor instance.
Returns
true if the link was inserted.unwrapLink
Unwraps a link node.
Parameters
The editor instance.
upsertLink
If the selection is in a link or the selection is not a URL:
- If
insertTextInLinkistrue, insert theurlas text in the link and exit. - Otherwise, if the
textis defined and empty, set it to theurl. - If
skipValidationisfalse(default), validate theurlusing thevalidateUrlfunction. 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
urlandtarget. - If
textis defined and not empty, replace the link text with the newtext.
Parameters
The editor instance.
Returns
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
The editor instance.
validateUrl
Validates a URL based on the plugin options.
Parameters
The editor instance.
The URL to validate.
Returns
true if the URL is valid.wrapLink
Wrap a link node with split.
Parameters
The editor instance.
CreateLinkNodeOptions
Attributes
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
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
The ref of the input element.
LinkOpenButton
The button to open the link.
State
The link element to open.
useFloatingLinkEdit
The behavior hook for the floating link edit.
State
The virtual floating returned object.
Returns
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
The virtual floating returned object.
The ref of the floating element.
Returns
The ref of the floating element.
Props
useFloatingLinkStore
The store for the floating link.
State
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
Returns
useLinkToolbarButton
The behavior hook for the link toolbar button.
State
Whether the selection is in a link.
Returns
useVirtualFloatingLink
Custom hook for managing virtual floating of a link.
Parameters
The ID of the editor to which the link belongs.
Options for virtual floating.
Returns
The return value of the useVirtualFloating hook.