Link

---
title: Link
docs:
  - route: https://pro.platejs.org/docs/examples/link
    title: Plus
  - route: /docs/components/link-node
    title: Link Element
  - route: /docs/components/link-toolbar
    title: Link Floating Toolbar
  - route: /docs/components/link-toolbar-button
    title: Link Toolbar Button
---

<ComponentPreview name="link-demo" />

<PackageInfo>

## Features

- Support for hyperlink insertion, edition and removal.

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add link functionality is with the `LinkKit`, which includes pre-configured `LinkPlugin` with floating toolbar and [Plate UI](/docs/installation/plate-ui) components.

<ComponentSource name="link-kit" />

- [`LinkElement`](/docs/components/link-node): Renders link elements.
- [`LinkFloatingToolbar`](/docs/components/link-toolbar): Provides floating toolbar for link editing.

### Add Kit

Add the kit to your plugins:

```tsx
import { createPlateEditor } from 'platejs/react';
import { LinkKit } from '@/components/editor/plugins/link-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...LinkKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/link
```

### Add Plugin

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

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

```tsx
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`](/docs/components/link-toolbar) after the editable area for link editing.
- `render.node`: Assigns [`LinkElement`](/docs/components/link-node) to render link elements.

### Add Toolbar Button

You can add [`LinkToolbarButton`](/docs/components/link-toolbar-button) to your [Toolbar](/docs/toolbar) to insert and edit links.

</Steps>

## Keyboard Shortcuts

<KeyTable>
  <KeyTableItem hotkey="Cmd + K">Add a link on the selected text.</KeyTableItem>
</KeyTable>

## Plate Plus

<ComponentPreviewPro name="link-pro" />

## Plugins

### `LinkPlugin`

Plugin for link formatting.

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

## Transforms

### `tf.insert.link`

Inserts a link node into the editor.

<API name="insert.link">
<APIParameters>
  <APIItem name="options" type="object">
    Options for inserting the link.
  </APIItem>
</APIParameters>
<APIOptions type="InsertLinkOptions">
  <APIItem name="createLinkNodeOptions" type="CreateLinkNodeOptions">
    Options for creating the link node.
  </APIItem>
  <APIItem name="insertOptions" type="InsertNodesOptions" optional>
    Additional options for inserting nodes.
  </APIItem>
 </APIOptions>
</API>

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

<API name="floatingLink.show">
<APIParameters>
<APIItem name="mode" type="FloatingLinkMode">
The mode to set for the floating link ('edit' or 'insert').
</APIItem>
<APIItem name="editorId" type="string">
The ID of the editor where the floating link should be shown.
</APIItem>
</APIParameters>
</API>

### `api.link.getAttributes`

Gets the attributes for a link element.

<API name="link.getAttributes">
<APIParameters>
<APIItem name="element" type="TLinkElement">
The link element for which to get attributes.
</APIItem>
</APIParameters>

<APIReturns type="React.AnchorHTMLAttributes<HTMLAnchorElement>">
The HTML attributes for the link element.
</APIReturns>
</API>

### `api.link.submitFloatingLink`

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

<APIReturns type="boolean">
Returns `true` if the link was inserted successfully.
</APIReturns>

### `insertLink`

Inserts a link node into the editor.

<API name="insertLink">
<APIParameters>
  <APIItem name="createLinkNodeOptions" type="CreateLinkNodeOptions">
    Options for creating link node.
  </APIItem>
  <APIItem name="options" type="InsertNodesOptions" optional>
    Additional options for node insertion.
  </APIItem>
</APIParameters>
</API>

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

<API name="submitFloatingLink">
<APIReturns type="boolean">
Returns `true` if the link was inserted.
</APIReturns>
</API>

### `triggerFloatingLink`

Triggers the floating link.

<API name="triggerFloatingLink">
<APIOptions type="object">
<APIItem name="focused" type="boolean" optional>
  Whether the floating link should be focused.
</APIItem>
</APIOptions>
</API>

### `triggerFloatingLinkEdit`

Triggers the floating link edit.

<API name="triggerFloatingLinkEdit">
<APIReturns type="boolean">
Returns `true` if the link was edited.
</APIReturns>
</API>

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

<API name="triggerFloatingLinkInsert">
<APIOptions type="TriggerFloatingLinkOptions">
  <APIItem name="focused" type="boolean" optional>
    Whether the floating link should be focused.
  </APIItem>
</APIOptions>

<APIReturns type="boolean">
  Returns `true` if the link was inserted.
</APIReturns>
</API>

### `unwrapLink`

Unwraps a link node.

<API name="unwrapLink">
<APIOptions type="UnwrapLinkOptions">
  <APIItem name="split" type="boolean" optional>
    If `true`, split the nodes if the selection is inside the link.
  </APIItem>
</APIOptions>
</API>

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

<API name="upsertLink">
<APIParameters>
  <APIItem name="options" type="UpsertLinkOptions">
    Options for upserting the link.
  </APIItem>
</APIParameters>

<APIOptions type="UpsertLinkOptions">
  <APIItem name="url" type="string">
    The URL of the link.
  </APIItem>
  <APIItem name="text" type="string" optional>
    The text content of the link.
  </APIItem>
  <APIItem name="target" type="string" optional>
    The target attribute of the link.
  </APIItem>
  <APIItem name="insertTextInLink" type="boolean" optional>
    If `true`, insert the URL as text in the link.
  </APIItem>
  <APIItem name="insertNodesOptions" type="InsertNodesOptions" optional>
    The options for inserting nodes.
  </APIItem>
  <APIItem name="skipValidation" type="boolean" optional>
    If `true`, skips URL validation.
    - **Default:** `false`
  </APIItem>
</APIOptions>

<APIReturns type="boolean">
  Returns `true` if the link was inserted or updated.
</APIReturns>
</API>

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

<API name="upsertLinkText">
<APIOptions type="UpsertLinkTextOptions">
      <APIItem name="text" type="string" optional>
        The new text to replace the link children with.
      </APIItem>
</APIOptions>
</API>

### `validateUrl`

Validates a URL based on the plugin options.

<API name="validateUrl">
<APIOptions type="ValidateUrlOptions">
  <APIItem name="url" type="string">
    The URL to validate.
  </APIItem>
</APIOptions>

<APIReturns type="boolean">
  Returns `true` if the URL is valid.
</APIReturns>
</API>

### `wrapLink`

Wrap a link node with split.

<API name="wrapLink">
<APIOptions type="WrapLinkOptions">
  <APIItem name="url" type="string">
    The URL of the link.
  </APIItem>
  <APIItem name="target" type="string" optional>
    The target attribute of the link.
  </APIItem>
</APIOptions>
</API>

### `CreateLinkNodeOptions`

Options for creating a new link node.

<API name="CreateLinkNodeOptions">
<APIOptions type="object">
  <APIItem name="url" type="string">
    The URL of the link node that is being created.
  </APIItem>
  <APIItem name="text" type="string" optional>
    The text that is displayed for the link node. If not provided, the URL is used as the display text.
  </APIItem>
  <APIItem name="target" type="string" optional>
    Specifies where to open the URL:
    - `_blank`: new tab
    - `_self`: same frame
    - `_parent`: parent frame
    - `_top`: full window
  </APIItem>
  <APIItem name="children" type="TText[]" optional>
    An array of text nodes that represent the link content.
  </APIItem>
</APIOptions>
</API>

## API Components

### `FloatingLinkNewTabInput`

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

<API name="FloatingLinkNewTabInput">
<APIState>
  <APIItem name="checked" type="boolean">
    Whether the link should open in a new tab.
  </APIItem>
  <APIItem name="setChecked" type="React.Dispatch<React.SetStateAction<boolean>>">
    Function to update the checked state.
  </APIItem>
  <APIItem name="ref" type="RefObject<HTMLInputElement>">
    Reference to the input element.
  </APIItem>
</APIState>
</API>

### `FloatingLinkUrlInput`

The input component for entering and editing link URLs.

<API name="FloatingLinkUrlInput">
<APIState>
  <APIItem name="ref" type="RefObject<HTMLInputElement>">
    Reference to the input element.
  </APIItem>
</APIState>
</API>

### `LinkOpenButton`

The button component for opening the link URL.

<API name="LinkOpenButton">
<APIState>
  <APIItem name="element" type="TLinkElement">
    The link element containing the URL to open.
  </APIItem>
</APIState>
</API>

### `useFloatingLinkEdit`

The behavior hook for the floating link edit functionality.

<API name="useFloatingLinkEdit">
<APIState>
  <APIItem name="floating" type="object" optional>
    The virtual floating returned object.
  </APIItem>
</APIState>

<APIReturns type="object">
  <APIItem name="ref" type="function">
    The ref callback for the floating element.
  </APIItem>
  <APIItem name="props" type="object">
    Props for the floating element.
    <APISubList>
      <APISubListItem parent="props" name="style" type="object">
        The style of the floating link.
      </APISubListItem>
    </APISubList>
  </APIItem>
  <APIItem name="editButtonProps" type="object">
    Props for the edit button.
    <APISubList>
      <APISubListItem parent="editButtonProps" name="onClick" type="function">
        The function to call when the edit button is clicked.
      </APISubListItem>
    </APISubList>
  </APIItem>
  <APIItem name="unlinkButtonProps" type="object">
    Props for the unlink button.
    <APISubList>
      <APISubListItem parent="unlinkButtonProps" name="onClick" type="function">
        The function to call when the unlink button is clicked.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIReturns>
</API>

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

<API name="useFloatingLinkInsert">
<APIState>
  <APIItem name="floating" type="ReturnType<typeof useFloatingLinkInsertState>">
    The virtual floating returned object.
  </APIItem>
  <APIItem name="refClickOutside" type="React.Ref">
    The ref of the floating element.
  </APIItem>
</APIState>

<APIReturns type="object">
  <APIItem name="ref" type="function">
    The ref callback for the floating element.
  </APIItem>
  <APIItem name="props" type="object">
    Props for the floating element.
    <APISubList>
      <APISubListItem parent="props" name="style" type="object">
        The style of the floating link.
      </APISubListItem>
    </APISubList>
  </APIItem>
  <APIItem name="textInputProps" type="object">
    Props for the text input.
    <APISubList>
      <APISubListItem parent="textInputProps" name="onChange" type="function">
        The function to call when the text input value changes.
      </APISubListItem>
      <APISubListItem parent="textInputProps" name="defaultValue" type="string">
        The default value of the text input.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIReturns>
</API>

### `useLink`

The behavior hook for the link element.

<API name="useLink">
<APIOptions type="UseLinkOptions">
  <APIItem name="element" type="TLinkElement">
    The link element.
  </APIItem>
</APIOptions>

<APIReturns type="object">
  <APIItem name="props" type="object">
    Props for the link element.
    <APISubList>
      <APISubListItem parent="props" name="onMouseOver" type="function">
        The function to call when the mouse is over the link.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIReturns>
</API>

### `useLinkToolbarButton`

The behavior hook for the link toolbar button.

<API name="useLinkToolbarButton">
<APIState>
  <APIItem name="pressed" type="boolean">
    Whether the selection is in a link.
  </APIItem>
</APIState>

<APIReturns type="object">
  <APIItem name="props" type="object">
    Props for the toolbar button.
    <APISubList>
      <APISubListItem parent="props" name="pressed" type="boolean">
        Whether the link is pressed.
      </APISubListItem>
      <APISubListItem parent="props" name="onClick" type="function">
        The function to call when the button is clicked.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIReturns>
</API>

### `useVirtualFloatingLink`

Custom hook for managing virtual floating of a link.

<API name="useVirtualFloatingLink">
<APIOptions type="object">
  <APIItem name="editorId" type="string">
    The ID of the editor to which the link belongs.
  </APIItem>
  <APIItem name="floatingOptions" type="UseVirtualFloatingOptions" optional>
    Options for virtual floating.
  </APIItem>
</APIOptions>

<APIReturns type="UseVirtualFloatingReturn">
  The return value of the `useVirtualFloating` hook.
</APIReturns>
</API>