Link Popover

LinkPopover provides a floating URL input popover for creating and editing links. It listens for the linkEdit event (emitted by the Link mark’s Mod-K shortcut and toolbar button) and toggles a popover with a URL input, apply button, and remove button. It auto-prepends https:// for bare URLs and validates against allowed protocols.

This is a UI extension - it creates DOM elements for the popover. In headless setups, omit this extension and build your own link editing UI by listening for the linkEdit event directly.

Included in StarterKit by default.

When to use

Use LinkPopover when you need:

A floating UI for editing the href of a selected link
Cmd+K to open the popover on the current selection
A built-in URL validator that strips javascript: and vbscript: URLs

Skip it if:

You build a custom link-editing UI (toolbar input, modal, sidebar)
Your editor is read-only or links are managed entirely server-side

Live Playground

Select text and press Cmd+K / Ctrl+K to open the URL popover. Type a URL and press Enter to apply, or click the remove button to unlink.

Themed
Headless

The editor includes the Link mark and LinkPopover with the default theme. Click the link toolbar button or press Cmd+K / Ctrl+K to open the URL popover. Enter a URL, press Enter to apply. Click an existing link and press Cmd+K to edit or remove it.

Click to try it out

Without LinkPopover, the Link mark still works but there is no built-in UI for entering URLs. The buttons below call setLink(), unsetLink(), and toggleLink() with a hardcoded URL to demonstrate the commands directly.

Click to try it out

Usage

LinkPopover is included in StarterKit, so it works out of the box. To use it standalone:

import { Document, Paragraph, Text, Link, LinkPopover } from '@domternal/core';
import { DomternalEditor } from '@domternal/vanilla';
import '@domternal/theme';

const dm = new DomternalEditor(document.getElementById('editor')!, {
  extensions: [Document, Paragraph, Text, Link, LinkPopover],
  content: '<p>Select text and press <code>Cmd+K</code> / <code>Ctrl+K</code> to add a link.</p>',
});

import { Component, signal } from '@angular/core';
import { DomternalEditorComponent } from '@domternal/angular';
import { Editor, Document, Paragraph, Text, Link, LinkPopover } from '@domternal/core';

@Component({
  selector: 'app-editor',
  imports: [DomternalEditorComponent],
  templateUrl: './editor.html',
})
export class EditorComponent {
  editor = signal<Editor | null>(null);
  extensions = [Document, Paragraph, Text, Link, LinkPopover];
  content = '<p>Select text and press Cmd+K / Ctrl+K to add a link.</p>';
}

<domternal-editor
  [extensions]="extensions"
  [content]="content"
  (editorCreated)="editor.set($event)"
/>

import { Domternal } from '@domternal/react';
import { Document, Paragraph, Text, Link, LinkPopover } from '@domternal/core';

export default function Editor() {
  return (
    <Domternal
      extensions={[Document, Paragraph, Text, Link, LinkPopover]}
      content="<p>Select text and press Cmd+K / Ctrl+K to add a link.</p>"
    >
      <Domternal.Content />
    </Domternal>
  );
}

<script setup lang="ts">
import { Domternal } from '@domternal/vue';
import { Document, Paragraph, Text, Link, LinkPopover } from '@domternal/core';

const extensions = [Document, Paragraph, Text, Link, LinkPopover];
</script>

<template>
  <Domternal :extensions="extensions" content="<p>Select text and press Cmd+K / Ctrl+K to add a link.</p>">
    <Domternal.Content />
  </Domternal>
</template>

In headless mode, you typically skip LinkPopover and handle the linkEdit event yourself:

import { Editor, Document, Paragraph, Text, Link } from '@domternal/core';

const editor = new Editor({
  element: document.getElementById('editor')!,
  extensions: [Document, Paragraph, Text, Link],
  content: '<p>Select text and press Cmd+K / Ctrl+K.</p>',
});

// Build your own link UI
editor.on('linkEdit', ({ anchorElement }) => {
  const url = prompt('URL:');
  if (url) editor.commands.setLink({ href: url });
});

To configure LinkPopover in StarterKit:

StarterKit.configure({
  linkPopover: { protocols: ['http:', 'https:'] },
})

To disable LinkPopover in StarterKit:

StarterKit.configure({ linkPopover: false })

LinkPopover declares dependencies: ['link']. Disabling the Link mark on its own leaves LinkPopover registered, and the editor throws at construction: Extension "linkPopover" requires "link" extension. Please add it to your extensions array. Disable both together:

StarterKit.configure({ link: false, linkPopover: false })

Options

Option	Type	Default	Description
`protocols`	`string[]`	`['http:', 'https:', 'mailto:', 'tel:']`	Allowed URL protocols for validation. Should match the Link mark’s `protocols` option.

import { LinkPopover } from '@domternal/core';

const editor = new Editor({
  extensions: [
    LinkPopover.configure({
      protocols: ['http:', 'https:', 'mailto:'],
    }),
  ],
});

Commands

LinkPopover does not register any commands. It uses the Link mark’s setLink and unsetLink commands internally.

Keyboard shortcuts

LinkPopover does not register its own keyboard shortcuts. It is triggered by the Link mark’s Mod-K shortcut, which emits a linkEdit event.

The popover itself supports keyboard navigation:

Key	Context	Action
`Enter`	In URL input	Apply the link
`Escape`	Anywhere in popover	Close the popover and return focus to the editor
`Tab`	In URL input	Move focus to the apply button
`Shift-Tab`	In URL input	Move focus to the remove button (if visible) or apply button
`Tab` / `Shift-Tab`	On buttons	Cycle focus between input, apply, and remove
`Enter`	On a button	Click the focused button

Input rules

LinkPopover does not register any input rules.

LinkPopover does not register any toolbar items. The toolbar link button is registered by the Link mark with emitEvent: 'linkEdit', which triggers this popover.

How it works

Event-driven toggle

LinkPopover listens for the linkEdit event on the editor. This event is emitted by:

The Link mark’s Mod-K keyboard shortcut
The Link toolbar button click (via emitEvent: 'linkEdit')

Each linkEdit event toggles the popover: if closed, it opens; if open, it closes and returns focus to the editor.

Opening behavior

When the popover opens, it:

Detects existing links - checks if the cursor or selection is inside a link mark. If so, pre-fills the input with the existing href and shows the remove button.
Shows a selection decoration - when text is selected, the browser hides the native selection highlight when the input takes focus. The plugin renders an inline dm-link-pending decoration to keep the selected text visually highlighted.
Positions with Floating UI - uses positionFloating() (which wraps @floating-ui/dom) to position the popover below the anchor element (toolbar button) or below the cursor position.
Focuses the input - auto-focuses and selects the URL input content.

Applying a link

When the user presses Enter or clicks the apply button:

Ignores an empty input - if the input is blank after trimming, the popover just closes and focus returns to the editor. An existing link is left untouched; removing a link is done with the remove button (unsetLink()) only.
Auto-prepends protocol - if the URL has no protocol (e.g., example.com), https:// is prepended automatically.
Validates the URL - checks the URL against the configured protocols list using isValidUrl(). Invalid URLs are silently rejected and the popover closes.
Handles existing links - if the cursor is inside an existing link with no selection, the plugin selects the full link range using getMarkRange() and updates the mark in a single transaction to avoid a visual flash.
Applies the mark - calls editor.commands.setLink({ href }) to set the link.
Closes and refocuses - hides the popover and returns focus to the editor.

Removing a link

The remove button calls editor.commands.unsetLink(), closes the popover, and returns focus to the editor. It is only visible when the cursor is inside an existing link.

Click outside

Clicking outside the popover closes it. Clicks on the toggle anchor element (the toolbar button that opened the popover) are ignored so the button’s own click handler can toggle correctly.

DOM structure

Where the popover lives in the DOM depends on how it was opened:

Opened from a button (toolbar or bubble menu, which pass an anchorElement with the linkEdit event): the popover is positioned against that button (placement: 'bottom-start'). If the button sits inside a .dm-editor wrapper, the popover is reparented there so it inherits the editor’s --dm-* custom properties. Bubble menu buttons qualify, since the bubble menu element is moved into .dm-editor when the plugin starts. A toolbar rendered next to the editor, the layout the framework guides use, does not, so the popover stays in document.body.
Opened from the Mod-K shortcut (no anchor): the popover stays in document.body, positioned below the cursor (placement: 'bottom'), so it is never clipped by overflow: hidden on the editor wrapper.

On every open the editor’s dm-theme-* class is copied onto the popover (copyThemeClass), which is what keeps dark-mode tokens resolving on the document.body path and lets runtime theme toggles propagate.

<div class="dm-link-popover" data-dm-editor-ui>
  <input class="dm-link-popover-input" type="url" placeholder="Enter URL..." aria-label="URL" />
  <button class="dm-link-popover-btn dm-link-popover-apply" aria-label="Apply link">
    <!-- check icon -->
  </button>
  <button class="dm-link-popover-btn dm-link-popover-remove" aria-label="Remove link">
    <!-- linkBreak icon -->
  </button>
</div>

Icons used: check (apply) and linkBreak (remove) from defaultIcons.

Selection decoration

While the popover is open with a text selection, the plugin maintains an inline decoration with the class dm-link-pending over the selected range. This paints a 12% tint of --dm-accent over the range (color-mix(in srgb, var(--dm-accent) 12%, transparent)), so the highlight follows a customized accent instead of a fixed blue. At the default --dm-accent of #2563eb it resolves to a light blue.

LinkPopover writes its open state to editor.storage.link.isOpen. This allows the Link toolbar button to show an “expanded” state while the popover is open.

Styling

The @domternal/theme package includes full styles for the link popover with light and dark theme support.

Class	Description
`.dm-link-popover`	Main popover container (fixed position, z-index 60)
`.dm-link-popover-input`	URL text input (min-width 14rem)
`.dm-link-popover-btn`	Shared button styles (1.5rem square)
`.dm-link-popover-apply`	Apply button (blue on hover)
`.dm-link-popover-remove`	Remove button (red on hover)
`.dm-link-pending`	Inline decoration on selected text while popover is open

Exports

import { LinkPopover } from '@domternal/core';
import type { LinkPopoverOptions } from '@domternal/core';

Export	Type	Description
`LinkPopover`	Extension	The link popover extension
`LinkPopoverOptions`	TypeScript type	Options for `LinkPopover.configure()`

Source

@domternal/core - LinkPopover.ts