ElementSelectionOverlay

When to use

Use it to build point-and-edit: click an element in a preview, then jump to its source, open a property panel, or feed it to a prompt. It only selects and reports a path; the editing panel is yours to build.

• To walk a user through an element you already know, use Tour; it masks the page and anchors a card, it does not pick elements.
• To attach an annotation bubble to an element, use Annotation.
• For a non-interactive decorative layer, use Watermark.

Import

Props

Events

ElementSelectionDetail is { path, source: "marked" | "structural", component, tagName, element, rect }. source tells you how trustworthy the path is: marked comes from the marker attribute and survives re-layout, while structural is derived from the DOM shape and may break when the DOM changes.

Accessibility

• The overlay is aria-hidden with pointer-events: none: it stays out of the accessibility tree, never takes focus, and never blocks the target.
• State is not encoded by color alone: hover draws a thin dashed box, selection draws a thick solid one, and the label spells out the component or element name.
• Keyboard reachable: tab to an element inside the target and press Enter or Space to select it, Escape to clear, so a pointer is never required.
• Offer an equivalent keyboard path in the host as well, such as a component list built with Tree bound to selectedPath. Choosing a node in a list always beats hunting on a canvas for screen reader users.
• The label avoids the top viewport edge automatically by flipping inside the box, so it is never clipped.

Pitfalls

• Cross-origin iframes are not supported, and the failure is never silent. When contentDocument cannot be read the component renders nothing and fires onError({ code: "cross-origin" }) once, plus a development warning. Three ways out: serve the preview same-origin (srcDoc or a same-origin proxy domain), mount an overlay inside the previewed page and post the path back to the host, or drop point-and-edit. This component deliberately ships no postMessage bridge, because that is a separate protocol and does not belong inside a UI component.
• Mark the tree whenever you can. A structural path is inferred from the DOM shape, so one extra sibling or a flipped conditional can point it somewhere else. Put data-hulian-path on component roots to get paths that survive re-layout.
• Elements inside an iframe live in another realm, so they are not instances of the host Element and node instanceof Element is always false. Use the exported asElement() when handling target events yourself; this is the classic silent failure of same-origin iframe work.
• interceptClicks defaults to true, which means the preview is not interactive while selecting: clicks are swallowed and mousedown defaults are blocked. Pass interceptClicks={false} to keep the preview usable, or toggle selection mode through enabled.
• The target root itself is not selectable. Hovering or clicking it counts as empty space and triggers onClear. Marker lookup also skips the root on purpose, since a marker there would collapse every element onto one path.
• `getBoundingClientRect` always returns zero in jsdom, and zero-area rects count as invisible, so no box renders in unit tests by default. Stub Element.prototype.getBoundingClientRect if you need to assert that a box exists, but do not assert coordinates, since they come from your own stub. Test coordinate logic through the toHostRect and computeLabelPosition pure functions instead.
• When the target is document.body, the portal layer lives inside the target. The component already filters out MutationObserver records caused by itself, which would otherwise loop forever; do the same in any observer you add.
• Client component: it reads the DOM and attaches listeners, so use it in a client context. It renders nothing during SSR.

Related

Tour · Annotation · Watermark · Flow · Tree