SelectionPopover

A floating toolbar that appears near a text selection and offers a comment-on-selection action with an inline composer. The component uses fixed-position Floating UI geometry, so the supplied selection anchor can flip or shift when it is near a viewport edge.

Choosing this component

Use SelectionPopover when you want readers to annotate or comment on a highlighted range of text — for example, in a document editor, review tool, or article surface. It is designed specifically for selection-scoped actions. For generic floating content or popovers unrelated to text selection, use the Popover component instead.

SelectionPopover does not render persistent comment highlights. Keep saved comment anchors in your own markup, or use ReviewEditor and the commentary anchoring utilities when you need editor-backed anchor tracking.

How it positions

The position prop accepts a viewport-relative anchor point — the same coordinate space returned by Range.getClientRects() and Range.getBoundingClientRect(). A typical consumer computes the anchor from the selected range and passes it directly:

const range = selection.getRangeAt(0);
const rect =
  Array.from(range.getClientRects()).find((clientRect) => {
    return clientRect.width > 0 && clientRect.height > 0;
  }) ?? range.getBoundingClientRect();
position = { x: rect.left + rect.width / 2, y: rect.top, height: rect.height };

The component treats that point as a Floating UI virtual anchor, not as the panel's top-left corner. It prefers an above-selection placement, but shifts or flips near viewport edges. Coordinates are not relative to a containing element — do not pass offsetLeft/offsetTop or any container-relative value.

Usage

<script lang="ts">
  import { onMount } from 'svelte';
  import type { SelectionPopoverPosition } from '@lostgradient/cinder';
  import { SelectionPopover } from '@lostgradient/cinder';

  type Comment = { id: string; body: string };

  let isOpen = $state(false);
  let position = $state<SelectionPopoverPosition | null>(null);
  let comments = $state<Comment[]>([]);

  /**
   * Bound reference to the text surface element.
   * `selectionchange` is a document-level event — the handler uses this
   * reference to scope detection to selections inside the surface only.
   */
  let surfaceElement = $state<HTMLElement | null>(null);

  onMount(() => {
    function handleSelectionChange(): void {
      if (!surfaceElement) return;
      const selection = window.getSelection();
      if (!selection || selection.isCollapsed || selection.rangeCount === 0) {
        isOpen = false;
        position = null;
        return;
      }
      const range = selection.getRangeAt(0);
      if (!surfaceElement.contains(range.commonAncestorContainer)) {
        isOpen = false;
        position = null;
        return;
      }
      const rect =
        Array.from(range.getClientRects()).find((clientRect) => {
          return clientRect.width > 0 && clientRect.height > 0;
        }) ?? range.getBoundingClientRect();
      if (rect.width === 0 && rect.height === 0) {
        isOpen = false;
        position = null;
        return;
      }
      position = { x: rect.left + rect.width / 2, y: rect.top, height: rect.height };
      isOpen = true;
    }

    document.addEventListener('selectionchange', handleSelectionChange);
    return () => document.removeEventListener('selectionchange', handleSelectionChange);
  });

  function handleClose(): void {
    isOpen = false;
    position = null;
  }

  function handleCommentSubmit(body: string): void {
    comments = [...comments, { id: crypto.randomUUID(), body }];
    handleClose();
  }
</script>

<article bind:this={surfaceElement}>
  <p>Select text in this paragraph to comment on it.</p>
</article>

<SelectionPopover
  id="my-selection-popover"
  open={isOpen}
  {position}
  onClose={handleClose}
  onCommentSubmit={handleCommentSubmit}
/>

Custom actions

By default the popover offers the comment flow: an "Add comment" button that expands into an inline composer. Pass an actions snippet to replace that flow with your own controls, such as a quote action. The snippet is called with { close }; calling close dismisses the popover through the same path as Escape and an outside click, so onClose fires.

<SelectionPopover
  id="quote-popover"
  open={isOpen}
  {position}
  label="Quote selection"
  onClose={handleClose}
>
  {#snippet actions({ close })}
    <Button
      size="sm"
      variant="ghost"
      label="Quote"
      onclick={() => {
        quoteSelection();
        close();
      }}
    />
  {/snippet}
</SelectionPopover>

With actions given:

• onCommentSubmit and onExpand are never called, and Enter and Space no longer expand the popover.
• Focus moves to the first action once the popover is positioned and open. If a pointer is still down, as in a drag-select, the move waits for the pointer to be released so the selection is not cut short. Open the popover once the selection gesture has finished where you can (for example on pointerup or selectionchange after a drag); keyboard selection with Shift and the arrow keys has no such release, so the move takes focus as soon as the popover is positioned.
• The actions are one Tab stop. Left and Right arrows move focus between them, and Home and End jump to the first and last. This is the same implementation Toolbar uses, so editable controls keep Home and End and let Left and Right move focus only at the matching caret boundary, and disabling or enabling an action re-computes the Tab stop.
• On close, focus returns to the element that had it before the popover opened. After a mouse selection that is usually the page body, so name a specific element yourself in onClose if focus should land somewhere else.
• Escape and a pointer press outside call onClose, exactly as without actions.
• Selection tracking stays with the caller, as in the other examples.

The label prop sets the toolbar's accessible name and defaults to "Selection actions". Give it a name that fits the actions you render.