Package Exports

js-element-picker
js-element-picker/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (js-element-picker) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

Basic example

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();
  },
});

Picking inside custom container

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();
  },
});

Start picking after custom event

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());

Custom overlay for hovering element

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:

Make something when target is changed

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}`),
});