@vybe-adk/dom-element-selector

React hook for visually selecting DOM elements on a page with an interactive overlay, element highlighting, and rich metadata extraction.

Installation

npm install @vybe-adk/dom-element-selector

Usage

import { useDomElementSelector } from "@vybe-adk/dom-element-selector";

function App() {
  const { startSelection, isSelecting, DomElementSelectorOverlay } =
    useDomElementSelector({
      onSelect: (info) => {
        console.log("Selected:", info.element);
        console.log("Path:", info.elementPath);
      },
      onCancel: () => {
        console.log("Cancelled");
      },
    });

  return (
    <>
      <button onClick={startSelection}>
        {isSelecting ? "Selecting..." : "Select Element"}
      </button>
      <DomElementSelectorOverlay />
    </>
  );
}

Options

Option	Type	Default	Description
onSelect	(info: DomElementSelectorInfo) => void	required	Called when an element is selected
onCancel	() => void	—	Called when selection is cancelled (Escape or click)
overlayColor	string	—	Custom overlay background color
highlightColor	string	"rgba(59, 130, 246, 0.5)"	Custom highlight color
showTooltip	boolean	—	Show element info tooltip on hover
filter	DomElementSelectorFilterFn	—	Filter which elements are selectable

Return Value

Property	Type	Description
startSelection	() => void	Activate selection mode
stopSelection	() => void	Deactivate selection mode
isSelecting	boolean	Whether selection mode is active
DomElementSelectorOverlay	React.FC	Overlay component to render in your tree

Output

The onSelect callback receives a DomElementSelectorInfo object:

Field	Type	Description
element	string	Human-readable name (e.g., Button "Submit", Link "Home")
elementPath	string	Simplified DOM path (e.g., main > section > button)
fullPath	string	Full DOM path with IDs and classes
cssClasses	string	CSS classes on the element
nearbyText	string	Text content in and around the element
nearbyElements	string	Info about sibling elements
computedStyles	string	Key computed CSS styles
accessibility	string	ARIA attributes, roles, etc.
selectedText	string | undefined	Any text the user had selected
boundingBox	{ x, y, width, height }	Element bounding rectangle
isFixed	boolean	Whether the element has fixed/sticky positioning
domElement	HTMLElement	The actual DOM element

Filtering

Use the filter option to control which elements can be selected:

const { startSelection, DomElementSelectorOverlay } = useDomElementSelector({
  onSelect: (info) => console.log(info),
  filter: (element, info) => {
    // Only allow selecting buttons and links
    return element.tagName === "BUTTON" || element.tagName === "A";
  },
});

Compatibility

Peer Dependency	Version
react	>= 18.0.0
react-dom	>= 18.0.0

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

MIT