Tiptap Link: change the destination without changing the words

An original venue-guide example contains the words “Visitor entrance map.” The destination points to an outdated map. The author needs to keep those words and replace the link across the whole phrase, even when the cursor is sitting inside “entrance.”

Configure link behavior for the authoring surface

In an existing Tiptap 3 application, configure its Link extension:

import Link from '@tiptap/extension-link';

const venueLinks = Link.configure({
  openOnClick: false,
  autolink: true,
  linkOnPaste: true,
  defaultProtocol: 'https'
});

Add this to the editor's existing extension list. If the installed StarterKit already supplies Link, configure that instance or disable it before registering a separate one. Keep one Link extension for the document, alongside the application's normal document and text support.

autolink recognizes URLs during typing. linkOnPaste can link selected text when the pasted content is a URL. defaultProtocol controls the protocol supplied for those automatic cases when the typed address omits one. It does not replace validation in a custom link dialog.

The editor's click policy and the reader page's navigation policy are separate. Preventing navigation while editing should not leave the published venue map impossible to open.

Apply a complete destination to the intended mark

For this example, the dialog accepts an absolute HTTPS URL. That is a deliberate venue-guide policy, so an email address or relative path should receive a useful validation message instead of being silently rewritten.

function setVenueLink(editor, enteredUrl) {
  const url = new URL(enteredUrl.trim());
  if (url.protocol !== 'https:') {
    throw new Error('Enter the complete HTTPS map address.');
  }

  return editor.chain()
    .focus()
    .extendMarkRange('link')
    .setLink({ href: url.href })
    .run();
}

Call this with the initialized editor after the author confirms the dialog. Catch validation errors in the dialog and keep it open with the entered value. new URL() can throw for incomplete input. Do not silently swallow the error and announce that the link changed.

The command assumes the author selected the phrase or placed the cursor inside the existing link. A collapsed cursor in unlinked text is a different case; require a meaningful selection before offering “Add link.” If opening the dialog changes editor selection in your integration, preserve and restore the intended selection through the supported application flow.

extendMarkRange expands the current selection to the surrounding mark. It does nothing when that mark is absent. Its command documentation also shows filtering by mark attributes and updating a mark's attributes directly.

Read the destination separately from its label

Use editor.getAttributes('link').href to populate the dialog from the current link. Reading attributes does not modify the document. A label that says “Visitor entrance map” tells you nothing about whether its destination is current.

Removing a destination should use unsetLink(). Preserve the linked words unless the user also asked to delete them. If the product supports mailto:, telephone links, or internal relative URLs, define and validate those accepted formats explicitly. Tiptap documents isAllowedUri for its link validation policy; do not replace the default validation with a callback that accepts every string.

The BubbleMenu guide covers placing controls near selected text. A link dialog also needs a clear label, validation feedback, and an explicit confirmation action.

Check the saved venue instruction

In the actual development editor, put the cursor in the middle of “Visitor entrance map” and change its old destination to a different test address. Inspect the supported document output: the entire phrase should retain one intended destination, the visible words should remain unchanged, and adjacent prose should stay unlinked.

Try pasting a complete URL onto selected text, typing a URL, and removing an existing link. These exercise different enabled behaviors. Save through the real application, reopen the venue guide, and inspect its reader view. Follow the map link there and confirm that the destination belongs to the venue the instruction describes.