> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superdoc.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Link popover

Control what happens when a user clicks a link in the editor. By default, SuperDoc shows a built-in popover with the link URL and edit controls. With `popoverResolver`, you can replace it with your own UI in any framework.

## Quick start

No configuration needed for the default behavior: click a link and the built-in popover appears.

To customize, add a `popoverResolver` to the `links` module:

```javascript theme={null}
new SuperDoc({
  selector: '#editor',
  document: file,
  modules: {
    links: {
      popoverResolver: (ctx) => {
        // Navigate anchor links instead of showing a popover
        if (ctx.isAnchorLink) {
          window.location.hash = ctx.href;
          return { type: 'none' };
        }
        // Everything else gets the default popover
        return { type: 'default' };
      }
    }
  }
});
```

## Configuration

**modules.links.popoverResolver** `(ctx: LinkPopoverContext) =\> LinkPopoverResolution | null | undefined`

Synchronous function called when a user clicks a link. Receives a [context object](#resolver-context) and returns a [resolution](#resolution-types) that determines which popover to show. Return `null` or `undefined` to use the default popover.

> [!WARNING]
>
> The resolver must be synchronous. Do not return a Promise. If the resolver throws, SuperDoc falls back to the default popover and calls `onException`.

## Resolver context

The resolver receives a `LinkPopoverContext` object with all information about the clicked link:

| Property | Type | Description |
| - | - | - |
| `editor` | `Editor` | The editor instance |
| `href` | `string` | The `href` attribute of the clicked link |
| `target` | `string \| null` | The `target` attribute |
| `rel` | `string \| null` | The `rel` attribute |
| `tooltip` | `string \| null` | The `title` attribute |
| `element` | `HTMLAnchorElement` | The clicked anchor DOM element |
| `clientX` | `number` | X coordinate of the click |
| `clientY` | `number` | Y coordinate of the click |
| `isAnchorLink` | `boolean` | `true` when href starts with `#` |
| `documentMode` | `string` | Current mode: `'editing'`, `'viewing'`, or `'suggesting'` |
| `position` | `{ left: string, top: string }` | Computed popover position relative to the editor surface |
| `closePopover` | `() => void` | Close the popover programmatically |

## Resolution types

The resolver returns one of four resolution types. Return `null` or `undefined` to use the default popover.

### `default`

Show the built-in link popover with URL display and edit controls.

```javascript theme={null}
popoverResolver: (ctx) => {
  return { type: 'default' };
}
```

### `none`

Suppress the popover entirely. Use this when the resolver handles the click itself (navigation, opening a modal, logging, etc.).

```javascript theme={null}
popoverResolver: (ctx) => {
  // Open external links in a new tab, no popover
  if (!ctx.isAnchorLink) {
    window.open(ctx.href, '_blank');
    return { type: 'none' };
  }
  return { type: 'default' };
}
```

### `custom`

Render a Vue component inside the built-in popover shell. `editor` and `closePopover` are automatically injected as props alongside any props you provide.

```javascript theme={null}
import MyLinkPopover from './MyLinkPopover.vue';

popoverResolver: (ctx) => {
  return {
    type: 'custom',
    component: MyLinkPopover,
    props: { href: ctx.href }
  };
}
```

Your component receives `editor`, `closePopover`, and any additional props:

```vue theme={null}
<script setup>
defineProps({
  editor: { type: Object, required: true },   // auto-injected
  closePopover: { type: Function, required: true }, // auto-injected
  href: { type: String },                     // your custom prop
});
</script>
```

### `external`

Mount framework-agnostic UI into a raw DOM container. Use this for React, Svelte, vanilla JS, or any non-Vue framework.

SuperDoc creates a positioned `<div>` element and passes it to your `render` function. You mount your UI into that container. Return a `{ destroy }` callback for cleanup when the popover closes.

```javascript theme={null}
popoverResolver: (ctx) => {
  return {
    type: 'external',
    render: ({ container, closePopover, editor, href }) => {
      // Mount your UI into the container
      container.innerHTML = `
        <a href="${href}" target="_blank">Open link</a>
        <button>Close</button>
      `;
      container.querySelector('button').onclick = closePopover;

      return {
        destroy: () => {
          // Clean up event listeners, unmount frameworks, etc.
        }
      };
    }
  };
}
```

The `render` function receives an `ExternalPopoverRenderContext`:

| Property | Type | Description |
| - | - | - |
| `container` | `HTMLElement` | Empty positioned DOM container to mount your UI into |
| `closePopover` | `() => void` | Close the popover, call `destroy`, and return focus to the editor |
| `editor` | `Editor` | The editor instance |
| `href` | `string` | The href of the clicked link |

> [!NOTE]
>
> The popover automatically closes on click-outside and Escape key: matching the built-in popover behavior. Your `destroy` callback is called in both cases.

## Framework examples

> [tab] React
>
> Use `createRoot` to mount a React component into the external container. Return `destroy` to unmount cleanly.
>
> ```jsx theme={null}
> import { createRoot } from 'react-dom/client';
> import { LinkPreview } from './LinkPreview';
>
> new SuperDoc({
>   selector: '#editor',
>   document: file,
>   modules: {
>     links: {
>       popoverResolver: (ctx) => ({
>         type: 'external',
>         render: ({ container, closePopover, href }) => {
>           const root = createRoot(container);
>           root.render(
>             <LinkPreview href={href} onClose={closePopover} />
>           );
>           return { destroy: () => root.unmount() };
>         }
>       })
>     }
>   }
> });
> ```
>
> With the React wrapper:
>
> ```jsx theme={null}
> import { SuperDocEditor } from '@superdoc-dev/react';
> import { createRoot } from 'react-dom/client';
> import { LinkPreview } from './LinkPreview';
>
> function App() {
>   return (
>     <SuperDocEditor
>       document={file}
>       documentMode="editing"
>       modules={{
>         links: {
>           popoverResolver: (ctx) => ({
>             type: 'external',
>             render: ({ container, closePopover, href }) => {
>               const root = createRoot(container);
>               root.render(
>                 <LinkPreview href={href} onClose={closePopover} />
>               );
>               return { destroy: () => root.unmount() };
>             }
>           })
>         }
>       }}
>     />
>   );
> }
> ```

> [tab] Vue
>
> Vue components can use the simpler `custom` type, which renders inside the built-in popover shell:
>
> ```javascript theme={null}
> import MyLinkPopover from './MyLinkPopover.vue';
>
> new SuperDoc({
>   selector: '#editor',
>   document: file,
>   modules: {
>     links: {
>       popoverResolver: (ctx) => ({
>         type: 'custom',
>         component: MyLinkPopover,
>         props: { href: ctx.href }
>       })
>     }
>   }
> });
> ```
>
> The `external` type also works with Vue if you prefer manual control:
>
> ```javascript theme={null}
> import { createApp } from 'vue';
> import MyLinkPopover from './MyLinkPopover.vue';
>
> popoverResolver: (ctx) => ({
>   type: 'external',
>   render: ({ container, closePopover, href }) => {
>     const app = createApp(MyLinkPopover, { href, closePopover });
>     app.mount(container);
>     return { destroy: () => app.unmount() };
>   }
> })
> ```

> [tab] Vanilla JS
>
> Build your popover with plain DOM APIs:
>
> ```javascript theme={null}
> new SuperDoc({
>   selector: '#editor',
>   document: file,
>   modules: {
>     links: {
>       popoverResolver: (ctx) => ({
>         type: 'external',
>         render: ({ container, closePopover, href }) => {
>           const link = document.createElement('a');
>           link.href = href;
>           link.target = '_blank';
>           link.textContent = href;
>           link.style.padding = '8px 12px';
>           link.style.display = 'block';
>           container.appendChild(link);
>
>           // No cleanup needed for simple DOM
>         }
>       })
>     }
>   }
> });
> ```

## Styling

External popovers use CSS custom properties with sensible defaults that match the built-in popover. Override them to match your design system.

### Shared popover variables

These apply to both the built-in popover and external link popovers:

| Variable | Default | Description |
| - | - | - |
| `--sd-popover-bg` | `white` | Background color |
| `--sd-popover-z-index` | `1000` | Stack order |
| `--sd-popover-radius` | `6px` | Border radius |
| `--sd-popover-shadow` | `0 0 0 1px rgba(0,0,0,0.05), 0px 10px 20px rgba(0,0,0,0.1)` | Box shadow |
| `--sd-popover-min-width` | `120px` | Minimum width |
| `--sd-popover-min-height` | `40px` | Minimum height |

### External link popover overrides

Override just the external link popover without affecting other popovers:

| Variable | Fallback | Description |
| - | - | - |
| `--sd-external-link-popover-bg` | `--sd-popover-bg` | Background color |
| `--sd-external-link-popover-z-index` | `--sd-popover-z-index` | Stack order |
| `--sd-external-link-popover-radius` | `--sd-popover-radius` | Border radius |
| `--sd-external-link-popover-shadow` | `--sd-popover-shadow` | Box shadow |
| `--sd-external-link-popover-min-width` | `--sd-popover-min-width` | Minimum width |
| `--sd-external-link-popover-min-height` | `--sd-popover-min-height` | Minimum height |

Example: dark theme for external link popovers:

```css theme={null}
.superdoc-root {
  --sd-external-link-popover-bg: #1a1a2e;
  --sd-external-link-popover-radius: 10px;
  --sd-external-link-popover-shadow: 0 8px 30px rgba(0, 0, 0, 0.25);
}
```

The external popover container also has the class `sd-external-link-popover` for direct CSS targeting:

```css theme={null}
.sd-external-link-popover {
  font-family: inherit;
  color: #333;
}
```

## Behavior

* **Toggle off**: Clicking a link while its popover is already open closes the popover.
* **Click outside**: Clicking anywhere outside the popover closes it.
* **Escape key**: Pressing Escape closes the popover.
* **Focus**: When a popover closes, focus returns to the editor.
* **Error handling**: If the resolver or `render` function throws, SuperDoc falls back to the default popover and calls the `onException` callback.
* **Cursor**: The editor cursor moves to the clicked link position before the resolver runs.

## Conditional resolution

Use resolver context to show different popovers based on link type, document mode, or any other condition:

```javascript theme={null}
popoverResolver: (ctx) => {
  // Anchor links: navigate without a popover
  if (ctx.isAnchorLink) {
    document.getElementById(ctx.href.slice(1))?.scrollIntoView();
    return { type: 'none' };
  }

  // Viewing mode: open links directly
  if (ctx.documentMode === 'viewing') {
    window.open(ctx.href, '_blank');
    return { type: 'none' };
  }

  // Internal links: custom component
  if (ctx.href.startsWith('https://internal.app/')) {
    return {
      type: 'custom',
      component: InternalLinkPopover,
      props: { href: ctx.href }
    };
  }

  // Everything else: default popover
  return { type: 'default' };
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.