60:I[314491,["/_next/static/immutable/chunks/3arlv5bvukoo2.js","/_next/static/immutable/chunks/39v64hmfyo-sr.js","/_next/static/immutable/chunks/2nvof3-29tvc3.js","/_next/static/immutable/chunks/3tjobt77z_9dj.js","/_next/static/immutable/chunks/04j_o97cgxn2x.js","/_next/static/immutable/chunks/3upr08c9vtj8w.js","/_next/static/immutable/chunks/1ww0328si-u8x.js","/_next/static/immutable/chunks/11mfl5ymqld9-.js","/_next/static/immutable/chunks/2xxcqy6ppds3l.js","/_next/static/immutable/chunks/1bpgyrs5qflhu.js","/_next/static/immutable/chunks/0-6vu2ul1h6ld.js","/_next/static/immutable/chunks/43_s7jweyypoh.js","/_next/static/immutable/chunks/0p6vao205o1jc.js","/_next/static/immutable/chunks/1_kyvgkyokw92.js","/_next/static/immutable/chunks/1lo-zn37dolb5.js","/_next/static/immutable/chunks/1v8k6yxw1rg0u.js"],"FilesView"] 61:T464b,--- 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 --- ## Features - Insert, edit, and remove hyperlinks. - Markdown shortcut: type `[text](url)` and close with `)` to turn it into a link. - Plain URL autolink: paste a URL, or type a URL then press space or `Enter`. ## Kit Usage ### Installation The fastest way to add link functionality is with the `LinkKit`, which includes pre-configured `LinkPlugin` with floating toolbar, autolink rules, and [Plate UI](/docs/installation/plate-ui) components. - [`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, ], }); ``` ## Manual Usage ### Installation ```bash npm install @platejs/link ``` ### Add Plugin Include `LinkPlugin` in your Plate plugins array when creating the editor. ```tsx import { LinkRules } from '@platejs/link'; 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: () => , }, }), ], }); ``` - `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. ### Input Rules Configure `LinkPlugin` to enable the built-in link input presets: ```tsx import { LinkPlugin } from '@platejs/link/react'; const editor = createPlateEditor({ plugins: [ LinkPlugin.configure({ inputRules: [ LinkRules.markdown(), LinkRules.autolink({ variant: 'paste' }), LinkRules.autolink({ variant: 'space' }), LinkRules.autolink({ variant: 'break' }), ], }), ], }); ``` - `LinkRules.autolink({ variant: 'paste' | 'space' | 'break' })`: Enables plain URL autolink. - `LinkRules.markdown()`: Enables `[text](url)` source-entry conversion on the closing `)`. ### Add Toolbar Button You can add [`LinkToolbarButton`](/docs/components/link-toolbar-button) to your [Toolbar](/docs/toolbar) to insert and edit links. ## Keyboard Shortcuts Add a link on the selected text. ## Plate Plus ## Plugins ### `LinkPlugin` Plugin for link formatting. Determines whether to force the submission of the link form. Allows custom configurations for rangeBeforeOptions. - **Default:** ```ts { 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`. ## Transforms ### `tf.insert.link` Inserts a link node into the editor. Options for inserting the link. Options for creating the link node. 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. The mode to set for the floating link ('edit' or 'insert'). The ID of the editor where the floating link should be shown. ### `api.link.getAttributes` Gets the attributes for a link element. The link element for which to get attributes. 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. Returns `true` if the link was inserted successfully. ### `insertLink` Inserts a link node into the editor. 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. Returns `true` if the link was inserted. ### `triggerFloatingLink` Triggers the floating link. Whether the floating link should be focused. ### `triggerFloatingLinkEdit` Triggers the floating link edit. 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 Whether the floating link should be focused. Returns `true` if the link was inserted. ### `unwrapLink` Unwraps a link node. 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 Options for upserting the link. 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` 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. The new text to replace the link children with. ### `validateUrl` Validates a URL based on the plugin options. The URL to validate. Returns `true` if the URL is valid. ### `wrapLink` Wrap a link node with split. The URL of the link. The target attribute of the link. ### `CreateLinkNodeOptions` Options for creating a new link node. 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. 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. Reference to the input element. ### `LinkOpenButton` The button component for opening the link URL. The link element containing the URL to open. ### `useFloatingLinkEdit` The behavior hook for the floating link edit functionality. The virtual floating returned object. The ref callback for the floating element. Props for the floating element. The style of the floating link. Props for the edit button. The function to call when the edit button is clicked. Props for the unlink button. The function to call when the unlink button is clicked. ### `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. The virtual floating returned object. The ref of the floating element. The ref callback for the floating element. Props for the floating element. The style of the floating link. Props for the text input. The function to call when the text input value changes. The default value of the text input. ### `useLink` The behavior hook for the link element. The link element. Props for the link element. The function to call when the mouse is over the link. ### `useLinkToolbarButton` The behavior hook for the link toolbar button. Whether the selection is in a link. Props for the toolbar button. Whether the link is pressed. The function to call when the button is clicked. ### `useVirtualFloatingLink` Custom hook for managing virtual floating of a link. The ID of the editor to which the link belongs. Options for virtual floating. The return value of the `useVirtualFloating` hook. 5f:["$","div",null,{"className":"mt-3 flex min-h-0 min-w-0 flex-1 flex-col gap-3","children":[null,["$","$L60",null,{"files":[{"path":"../../content/docs/(plugins)/(elements)/link.mdx","content":"$61","type":"registry:file","target":"content/docs/plate/(plugins)/(elements)/link.mdx"}],"className":"h-[70svh] min-h-80"}]]}]