{
"$schema": "https://ui.shadcn.com/schema/registry-item.json",
"name": "link-docs",
"title": "Link",
"description": "Documentation for Link",
"files": [
{
"path": "../../content/docs/(plugins)/(elements)/link.mdx",
"content": "---\ntitle: Link\ndocs:\n - route: https://pro.platejs.org/docs/examples/link\n title: Plus\n - route: /docs/components/link-node\n title: Link Element\n - route: /docs/components/link-toolbar\n title: Link Floating Toolbar\n - route: /docs/components/link-toolbar-button\n title: Link Toolbar Button\n---\n\n\n\n\n\n## Features\n\n- Insert, edit, and remove hyperlinks.\n- Markdown shortcut: type `[text](url)` and close with `)` to turn it into a link.\n- Plain URL autolink: paste a URL, or type a URL then press space or `Enter`.\n\n\n\n## Kit Usage\n\n\n\n### Installation\n\nThe 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.\n\n\n\n- [`LinkElement`](/docs/components/link-node): Renders link elements.\n- [`LinkFloatingToolbar`](/docs/components/link-toolbar): Provides floating toolbar for link editing.\n\n### Add Kit\n\nAdd the kit to your plugins:\n\n```tsx\nimport { createPlateEditor } from 'platejs/react';\nimport { LinkKit } from '@/components/editor/plugins/link-kit';\n\nconst editor = createPlateEditor({\n plugins: [\n // ...otherPlugins,\n ...LinkKit,\n ],\n});\n```\n\n\n\n## Manual Usage\n\n\n\n### Installation\n\n```bash\nnpm install @platejs/link\n```\n\n### Add Plugin\n\nInclude `LinkPlugin` in your Plate plugins array when creating the editor.\n\n```tsx\nimport { LinkRules } from '@platejs/link';\nimport { LinkPlugin } from '@platejs/link/react';\nimport { createPlateEditor } from 'platejs/react';\n\nconst editor = createPlateEditor({\n plugins: [\n // ...otherPlugins,\n LinkPlugin,\n ],\n});\n```\n\n### Configure Plugin\n\nConfigure the plugin with floating toolbar and custom components.\n\n```tsx\nimport { LinkPlugin } from '@platejs/link/react';\nimport { createPlateEditor } from 'platejs/react';\nimport { LinkElement } from '@/components/ui/link-node';\nimport { LinkFloatingToolbar } from '@/components/ui/link-toolbar';\n\nconst editor = createPlateEditor({\n plugins: [\n // ...otherPlugins,\n LinkPlugin.configure({\n render: {\n node: LinkElement,\n afterEditable: () => ,\n },\n }),\n ],\n});\n```\n\n- `render.afterEditable`: Renders [`LinkFloatingToolbar`](/docs/components/link-toolbar) after the editable area for link editing.\n- `render.node`: Assigns [`LinkElement`](/docs/components/link-node) to render link elements.\n\n### Input Rules\n\nConfigure `LinkPlugin` to enable the built-in link input presets:\n\n```tsx\nimport { LinkPlugin } from '@platejs/link/react';\n\nconst editor = createPlateEditor({\n plugins: [\n LinkPlugin.configure({\n inputRules: [\n LinkRules.markdown(),\n LinkRules.autolink({ variant: 'paste' }),\n LinkRules.autolink({ variant: 'space' }),\n LinkRules.autolink({ variant: 'break' }),\n ],\n }),\n ],\n});\n```\n\n- `LinkRules.autolink({ variant: 'paste' | 'space' | 'break' })`: Enables plain URL autolink.\n- `LinkRules.markdown()`: Enables `[text](url)` source-entry conversion on the closing `)`.\n\n### Add Toolbar Button\n\nYou can add [`LinkToolbarButton`](/docs/components/link-toolbar-button) to your [Toolbar](/docs/toolbar) to insert and edit links.\n\n\n\n## Keyboard Shortcuts\n\n\n Add a link on the selected text.\n\n\n## Plate Plus\n\n\n\n## Plugins\n\n### `LinkPlugin`\n\nPlugin for link formatting.\n\n\n\n\nDetermines whether to force the submission of the link form.\n\n\nAllows custom configurations for rangeBeforeOptions.\n- **Default:**\n```ts\n{\n matchString: ' ',\n skipInvalid: true,\n afterMatch: true,\n}\n```\n\n\nHotkeys to trigger floating link.\n- **Default:** **`'meta+k, ctrl+k'`**\n\n\nList of allowed URL schemes.\n- **Default:** **`['http', 'https', 'mailto', 'tel']`**\n\n\nDetermines whether the sanitation of links should be skipped.\n- **Default:** **`false`**\n\n\nDefault HTML attributes for link elements.\n- **Default:** **`{}`**\n\n\nKeeps selected text on pasting links by default.\n- **Default:** **`true`**\n\n boolean\" optional>\nCallback function to validate a URL.\n- **Default:** **`isUrl`**\n\n string | undefined\" optional>\nCallback 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`.\n\n string | undefined\" optional>\nCallback function to optionally transform the submitted URL provided by the user to the URL input before validation.\n\n Promise\" optional>\nOn 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`.\n\n\n\n\n## Transforms\n\n### `tf.insert.link`\n\nInserts a link node into the editor.\n\n\n\n \n Options for inserting the link.\n \n\n\n \n Options for creating the link node.\n \n \n Additional options for inserting nodes.\n \n \n\n\n## API\n\n### `api.floatingLink.hide`\n\nHides the floating link and resets its state.\n\n### `api.floatingLink.reset`\n\nResets the floating link state without changing the openEditorId.\n\n### `api.floatingLink.show`\n\nShows the floating link for the specified mode and editor ID.\n\n\n\n\nThe mode to set for the floating link ('edit' or 'insert').\n\n\nThe ID of the editor where the floating link should be shown.\n\n\n\n\n### `api.link.getAttributes`\n\nGets the attributes for a link element.\n\n\n\n\nThe link element for which to get attributes.\n\n\n\n\">\nThe HTML attributes for the link element.\n\n\n\n### `api.link.submitFloatingLink`\n\nInserts a link if the URL is valid, closes the floating link, and focuses the editor.\n\n\nReturns `true` if the link was inserted successfully.\n\n\n### `insertLink`\n\nInserts a link node into the editor.\n\n\n\n \n Options for creating link node.\n \n \n Additional options for node insertion.\n \n\n\n\n### `submitFloatingLink`\n\nInserts a link if the URL is valid, closes the floating link, and focuses the editor.\n\n- Insert link if url is valid.\n- Text is url if empty.\n- Close floating link.\n- Focus editor.\n\n\n\nReturns `true` if the link was inserted.\n\n\n\n### `triggerFloatingLink`\n\nTriggers the floating link.\n\n\n\n\n Whether the floating link should be focused.\n\n\n\n\n### `triggerFloatingLinkEdit`\n\nTriggers the floating link edit.\n\n\n\nReturns `true` if the link was edited.\n\n\n\n### `triggerFloatingLinkInsert`\n\nTrigger floating link. Do not trigger when:\n- Selection is across blocks\n- Selection has more than one leaf node\n- Lowest selection is not text\n- Selection has a link node\n\n\n\n \n Whether the floating link should be focused.\n \n\n\n\n Returns `true` if the link was inserted.\n\n\n\n### `unwrapLink`\n\nUnwraps a link node.\n\n\n\n \n If `true`, split the nodes if the selection is inside the link.\n \n\n\n\n### `upsertLink`\n\nInsert or update a link node. The behavior depends on the current selection and options:\n\n- If selection is in a link or not a URL:\n - With `insertTextInLink: true`, inserts URL as text in link\n - Otherwise, if `text` is empty, sets it to URL\n - Validates URL unless `skipValidation: true`\n- If selection is expanded or `update: true` in a link:\n - Removes link node and gets link text\n- Then:\n - Inserts link node with updated URL and target\n - If `text` is provided, replaces link text\n\n\n\n \n Options for upserting the link.\n \n\n\n\n \n The URL of the link.\n \n \n The text content of the link.\n \n \n The target attribute of the link.\n \n \n If `true`, insert the URL as text in the link.\n \n \n The options for inserting nodes.\n \n \n If `true`, skips URL validation.\n - **Default:** `false`\n \n\n\n\n Returns `true` if the link was inserted or updated.\n\n\n\n### `upsertLinkText`\n\nIf 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.\n\n\n\n \n The new text to replace the link children with.\n \n\n\n\n### `validateUrl`\n\nValidates a URL based on the plugin options.\n\n\n\n \n The URL to validate.\n \n\n\n\n Returns `true` if the URL is valid.\n\n\n\n### `wrapLink`\n\nWrap a link node with split.\n\n\n\n \n The URL of the link.\n \n \n The target attribute of the link.\n \n\n\n\n### `CreateLinkNodeOptions`\n\nOptions for creating a new link node.\n\n\n\n \n The URL of the link node that is being created.\n \n \n The text that is displayed for the link node. If not provided, the URL is used as the display text.\n \n \n Specifies where to open the URL:\n - `_blank`: new tab\n - `_self`: same frame\n - `_parent`: parent frame\n - `_top`: full window\n \n \n An array of text nodes that represent the link content.\n \n\n\n\n## API Components\n\n### `FloatingLinkNewTabInput`\n\nThe input component for controlling whether a link opens in a new tab.\n\n\n\n \n Whether the link should open in a new tab.\n \n >\">\n Function to update the checked state.\n \n \">\n Reference to the input element.\n \n\n\n\n### `FloatingLinkUrlInput`\n\nThe input component for entering and editing link URLs.\n\n\n\n \">\n Reference to the input element.\n \n\n\n\n### `LinkOpenButton`\n\nThe button component for opening the link URL.\n\n\n\n \n The link element containing the URL to open.\n \n\n\n\n### `useFloatingLinkEdit`\n\nThe behavior hook for the floating link edit functionality.\n\n\n\n \n The virtual floating returned object.\n \n\n\n\n \n The ref callback for the floating element.\n \n \n Props for the floating element.\n \n \n The style of the floating link.\n \n \n \n \n Props for the edit button.\n \n \n The function to call when the edit button is clicked.\n \n \n \n \n Props for the unlink button.\n \n \n The function to call when the unlink button is clicked.\n \n \n \n\n\n\n### `useFloatingLinkEnter`\n\nListens for the Enter key press event and submits the floating link in the editor.\n\n### `useFloatingLinkEscape`\n\nListens for the Escape key press event and handles the behavior of the floating link in the editor.\n\n### `useFloatingLinkInsert`\n\nThe behavior hook for inserting a link.\n\n\n\n \">\n The virtual floating returned object.\n \n \n The ref of the floating element.\n \n\n\n\n \n The ref callback for the floating element.\n \n \n Props for the floating element.\n \n \n The style of the floating link.\n \n \n \n \n Props for the text input.\n \n \n The function to call when the text input value changes.\n \n \n The default value of the text input.\n \n \n \n\n\n\n### `useLink`\n\nThe behavior hook for the link element.\n\n\n\n \n The link element.\n \n\n\n\n \n Props for the link element.\n \n \n The function to call when the mouse is over the link.\n \n \n \n\n\n\n### `useLinkToolbarButton`\n\nThe behavior hook for the link toolbar button.\n\n\n\n \n Whether the selection is in a link.\n \n\n\n\n \n Props for the toolbar button.\n \n \n Whether the link is pressed.\n \n \n The function to call when the button is clicked.\n \n \n \n\n\n\n### `useVirtualFloatingLink`\n\nCustom hook for managing virtual floating of a link.\n\n\n\n \n The ID of the editor to which the link belongs.\n \n \n Options for virtual floating.\n \n\n\n\n The return value of the `useVirtualFloating` hook.\n\n\n",
"type": "registry:file",
"target": "content/docs/plate/(plugins)/(elements)/link.mdx"
}
],
"type": "registry:file"
}