or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

autolink.mdclick-handling.mdindex.mdlink-commands.mdlink-configuration.mdpaste-processing.mdurl-validation.md
tile.json

tessl/npm-tiptap--extension-link

Link extension for tiptap rich text editor providing automatic link detection, paste handling, click behavior, and XSS protection.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@tiptap/extension-link@3.4.x

To install, run

npx @tessl/cli install tessl/npm-tiptap--extension-link@3.4.0

index.mddocs/

Tiptap Link Extension

The @tiptap/extension-link package provides comprehensive link functionality for the Tiptap rich text editor. It includes automatic link detection as users type, intelligent paste handling that converts pasted URLs into links, customizable click behavior with optional link opening, and robust XSS protection through URL validation.

Package Information

  • Package Name: @tiptap/extension-link
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @tiptap/extension-link

Core Imports

import { Link } from "@tiptap/extension-link";

All exports are also available as named imports:

import { 
  Link, 
  isAllowedUri, 
  pasteRegex, 
  LinkOptions, 
  LinkProtocolOptions,
  UNICODE_WHITESPACE_PATTERN,
  UNICODE_WHITESPACE_REGEX,
  UNICODE_WHITESPACE_REGEX_END,
  UNICODE_WHITESPACE_REGEX_GLOBAL
} from "@tiptap/extension-link";

CommonJS:

const { Link } = require("@tiptap/extension-link");

Basic Usage

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

// Create editor with Link extension
const editor = new Editor({
  extensions: [
    Link.configure({
      openOnClick: true,
      autolink: true,
      linkOnPaste: true,
      HTMLAttributes: {
        target: "_blank",
        rel: "noopener noreferrer nofollow",
      },
    }),
  ],
  content: '<p>Type or paste a URL like https://tiptap.dev to see automatic linking!</p>',
});

// Programmatically set links
editor.commands.setLink({ href: "https://tiptap.dev" });

// Toggle links
editor.commands.toggleLink({ href: "https://example.com" });

// Remove links
editor.commands.unsetLink();

Architecture

The Link extension is built around several key components:

  • Link Mark: ProseMirror mark-based link implementation with HTML attribute support
  • Command System: Chainable commands for link manipulation (setLink, toggleLink, unsetLink)
  • Plugin System: Multiple ProseMirror plugins for autolink, click handling, and paste processing
  • XSS Protection: URI validation system preventing malicious links
  • Protocol Support: Custom protocol registration beyond standard http/https
  • Helper Modules: Specialized modules for autolink detection, click handling, paste processing, and whitespace handling

Capabilities

Link Extension Configuration

Core Link extension class with comprehensive configuration options for behavior, validation, and appearance customization.

const Link: Mark<LinkOptions>;

interface LinkOptions {
  /** Enable automatic link creation as you type */
  autolink: boolean;
  /** Custom protocols to register with linkifyjs */
  protocols: Array<LinkProtocolOptions | string>;
  /** Default protocol when none specified */
  defaultProtocol: string;
  /** Enable link opening on click */
  openOnClick: boolean | 'whenNotEditable';
  /** Select link when clicked */
  enableClickSelection: boolean;
  /** Add links when pasting URLs */
  linkOnPaste: boolean;
  /** HTML attributes for link elements */
  HTMLAttributes: Record<string, any>;
  /** XSS protection URI validation function */
  isAllowedUri: (url: string, ctx: ValidationContext) => boolean;
  /** Determines if URL should be auto-linked */
  shouldAutoLink: (url: string) => boolean;
  /** @deprecated Use shouldAutoLink */
  validate: (url: string) => boolean;
}

interface LinkProtocolOptions {
  /** Protocol scheme to register */
  scheme: string;
  /** Allow optional slashes after protocol */
  optionalSlashes?: boolean;
}

Link Extension Configuration

Link Commands

Editor commands for programmatic link manipulation with chainable API integration.

interface LinkCommands {
  /** Set a link mark on the current selection */
  setLink: (attributes: {
    href: string;
    target?: string | null;
    rel?: string | null;
    class?: string | null;
  }) => ReturnType;
  
  /** Toggle a link mark on the current selection */
  toggleLink: (attributes?: {
    href: string;
    target?: string | null;
    rel?: string | null;
    class?: string | null;
  }) => ReturnType;
  
  /** Remove link mark from current selection */
  unsetLink: () => ReturnType;
}

Link Commands

URL Validation and Security

XSS protection utilities and URI validation for secure link handling.

function isAllowedUri(
  uri: string | undefined,
  protocols?: LinkOptions['protocols']
): boolean;

const pasteRegex: RegExp;

interface ValidationContext {
  /** Default validation function */
  defaultValidate: (url: string) => boolean;
  /** Array of allowed protocols */
  protocols: Array<LinkProtocolOptions | string>;
  /** Default protocol */
  defaultProtocol: string;
}

URL Validation

Automatic Link Detection

Smart link detection system with tokenization and validation for creating links as users type.

function autolink(options: AutolinkOptions): Plugin;

interface AutolinkOptions {
  /** Link mark type */
  type: MarkType;
  /** Default protocol */
  defaultProtocol: string;
  /** URL validation function */
  validate: (url: string) => boolean;
  /** Auto-link decision function */
  shouldAutoLink: (url: string) => boolean;
}

Automatic Link Detection

Click Handling

Click event processing for link navigation with configurable behavior and selection options.

function clickHandler(options: ClickHandlerOptions): Plugin;

interface ClickHandlerOptions {
  /** Link mark type */
  type: MarkType;
  /** Tiptap editor instance */
  editor: Editor;
  /** Enable click selection */
  enableClickSelection?: boolean;
}

Click Handling

Paste Processing

Intelligent URL paste handling that automatically converts pasted URLs into clickable links.

function pasteHandler(options: PasteHandlerOptions): Plugin;

interface PasteHandlerOptions {
  /** Tiptap editor instance */
  editor: Editor;
  /** Default protocol */
  defaultProtocol: string;
  /** Link mark type */
  type: MarkType;
}

Paste Processing

Whitespace Utilities

Unicode whitespace utilities for robust URL processing and validation, sourced from DOMPurify patterns.

/** Unicode whitespace pattern from DOMPurify */
export const UNICODE_WHITESPACE_PATTERN: string;

/** RegExp for matching Unicode whitespace */
export const UNICODE_WHITESPACE_REGEX: RegExp;

/** RegExp for matching whitespace at end of string */
export const UNICODE_WHITESPACE_REGEX_END: RegExp;

/** Global RegExp for replacing Unicode whitespace */
export const UNICODE_WHITESPACE_REGEX_GLOBAL: RegExp;

Types

/** @deprecated Use boolean instead */
type DeprecatedOpenWhenNotEditable = 'whenNotEditable';