js-element-picker

JavaScript/TypeScript library for selecting elements on a web page.

Installation

Install with npm:

npm install js-element-picker

Or yarn:

yarn add js-element-picker

React wrapper

For this library there is a React wrapper react-js-element-picker, which you can see here

Simple example

import { ElementPicker } from 'js-element-picker';

new ElementPicker({
  picking: true,
  onClick: (target) => alert(`Picked element: ${target.tagName}`),
});

Constructor arguments

| Name | Type | Default | Description |-------------|-------------|---------|-------------| | picking | boolean | |if true, starts picking immediately after initialization| | container | Element | document |if container was passed, picking will be inside of this container| | overlayDrawer | Function | Default overlay |See type below. If overlayDrawer was passed, it will be drawn instead of default overlay on the hovering element| | onTargetChange | (target?: Element, event?: MouseEvent) => void; | |callback that will fire every time when hovering target was changed| | onClick | (target: Element, event?: MouseEvent) => void; | |callback that fires when user clicks on the picked element|

overlayDrawer type:

overlayDrawer?: (
    position?: { x: number; y: number; width: number; height: number } | null,
    event?: MouseEvent | null
  ) => Element;

Methods:

• startPicking() - start picking elements
• stopPicking() - stop picking elements

Examples

In this example you create ElementPicker object which starts picking immediately after initialization and after click on target logs it in console and stops picking

import { ElementPicker } from 'js-element-picker';

const elementPicker = new ElementPicker({
  picking: true,
  onClick: (target) => {
    console.log(`Picked element: ${target?.tagName}`);
    elementPicker.stopPicking();
  },
});

By default ElementPicker picks inside the document. If you want to pick elements inside custom container, you need to pass it as container argument

Please note that if you DOM is not initialized and your customContainer is null, it couldn't work in a right way. So be sure that your container exists

So first

import { ElementPicker } from 'js-element-picker';

const customContainer = document.getElementById('my-custom-container');

const elementPicker = new ElementPicker({
  picking: true,
  container: customContainer,
  onClick: (target) => {
    console.log(`Picked element: ${target?.tagName}`);
    elementPicker.stopPicking();
  },
});

If you want to start picking on any event (for example, button click), you can use startPicking() method

import { ElementPicker } from 'js-element-picker';

const button = document.getElementById('start-pick');

const elementPicker = new ElementPicker({
  onClick: (target) => {
    console.log(`Picked element: ${target}`);
    elementPicker.stopPicking();
  },
});

button?.addEventListener('click', () => elementPicker.startPicking());

If you want to create custom overlay for hovering element, you need to pass overlayDrawer() function. It gets position and event as arguments and must return an Element. Result element will appear inside of overlay, so you don't need to think about positioning. Actually position is some fields from event just to make it easier to get.

So first you need to create a function for overlay drawer:

const myCustomOverlayDrawer = (
  position: { x: number; y: number; width: number; height: number } | null,
  event: MouseEvent | null
) => {
  const overlay = document.createElement('div');

  overlay.style.width = '100%';
  overlay.style.height = '100%';
  overlay.style.background = 'rgba(255, 0, 166, 0.8)';
  overlay.style.display = 'flex';

  overlay.style.display = 'flex';
  overlay.style.flexDirection = 'column';
  overlay.style.justifyContent = 'center';
  overlay.style.alignItems = 'center';
  overlay.style.gap = '8px';
  overlay.style.color = 'white';
  overlay.style.fontFamily = 'monospace';

  const tagNameSpan = document.createElement('span');
  const target = event?.target as Element;
  tagNameSpan.append(target?.tagName);
  overlay.append(tagNameSpan);

  if (position) {
    const positionSpan = document.createElement('span');
    positionSpan.append(`{x: ${position.x}, y: ${position.y}}`);
    overlay.append(positionSpan);
  }

  return overlay;
};

And then you can use it:

import { ElementPicker } from 'js-element-picker';

const elementPicker = new ElementPicker({
  picking: true,
  onClick: (target) => {
    console.log(`Picked element: ${target}`);
    elementPicker.stopPicking();
  },
  overlayDrawer: myCustomOverlayDrawer,
});

As a result you'll see something like this:

If you want to make something while user is picking elements, you can use onTargetChange argument. That is function which will fire every time when target was updated

import { ElementPicker } from 'js-element-picker';

new ElementPicker({
  picking: true,
  onTargetChange: (target) => console.log(`Hovering element: ${target?.tagName}`),
});