Link

Create clickable links in your editor.

The Link extension allows you to create clickable links. Links are rendered as <a> HTML elements with support for various attributes including href, target, rel, class, and title.

Installation

npm

npm install @tiptap/extension-link

Usage

import { Editor } from '@tiptap/core'
import Link from '@tiptap/extension-link'

const editor = new Editor({
  extensions: [
    Link.configure({
      openOnClick: true,
      linkOnPaste: true,
    }),
  ],
})

Configuration Options

autolink · boolean · default: "true"

If enabled, the extension will automatically add links as you type.

Link.configure({
  autolink: false,
})

protocols · Array<LinkProtocolOptions | string> · default: "[]"

An array of custom protocols to be registered with linkifyjs.

Link.configure({
  protocols: ['ftp', 'git'],
})

defaultProtocol · string · default: "'http'"

Default protocol to use when no protocol is specified.

Link.configure({
  defaultProtocol: 'https',
})

openOnClick · boolean · default: "true"

If enabled, links will be opened on click.

Link.configure({
  openOnClick: false,
})

enableClickSelection · boolean · default: "false"

If enabled, the link will be selected when clicked.

Link.configure({
  enableClickSelection: true,
})

linkOnPaste · boolean · default: "true"

Adds a link to the current selection if the pasted content only contains a URL.

Link.configure({
  linkOnPaste: false,
})

HTMLAttributes · Record<string, any>

HTML attributes to add to the link element.

Link.configure({
  HTMLAttributes: {
    class: 'my-link-class',
    rel: 'noopener noreferrer',
    target: '_blank',
  },
})

isAllowedUri · function

A validation function used for configuring link verification to prevent XSS attacks. Only modify this if you know what you’re doing.

Link.configure({
  isAllowedUri: (url, ctx) => {
    return url.startsWith('./') || ctx.defaultValidate(url)
  },
})

shouldAutoLink · function

Determines whether a valid link should be automatically linked in the content.

Link.configure({
  shouldAutoLink: (url) => {
    return url.startsWith('https://')
  },
})

Commands

setLink(attributes)

Set a link mark with the specified attributes. Supports href, target, rel, class, and title attributes.

editor.commands.setLink({ 
  href: 'https://tiptap.dev',
  target: '_blank',
  title: 'Tiptap Documentation'
})

toggleLink(attributes)

Toggle a link mark with the specified attributes.

editor.commands.toggleLink({ 
  href: 'https://tiptap.dev' 
})

unsetLink()

Remove the link mark from the current selection.

editor.commands.unsetLink()

Link Attributes

The Link extension supports the following attributes:

• href - The URL the link points to
• target - Where to open the link (e.g., _blank)
• rel - The relationship between the current document and the linked document
• class - CSS class name(s) for the link
• title - Tooltip text displayed when hovering over the link (added in v3.19.0)

Security

The Link extension includes built-in XSS protection. By default, it only allows safe protocols:

• http, https
• ftp, ftps
• mailto, tel, callto, sms
• cid, xmpp

You can customize this behavior using the isAllowedUri option, but be careful to maintain security when doing so.

Autolink Behavior

When autolink is enabled (default), the extension will automatically create links when you:

• Type or paste a URL with an explicit protocol (e.g., https://example.com)
• Type a domain with a TLD (e.g., example.com)

The extension will NOT autolink:

• IP addresses without a protocol
• Single-word hostnames without a TLD (e.g., localhost)
• URLs typed inside inline code marks

Source Code

View the source code on GitHub:

• packages/extension-link