npm.io
1.1.0 • Published 2 months ago

js-element-picker

Licence
ISC
Version
1.1.0
Deps
0
Size
57 kB
Vulns
0
Weekly
0
Stars
3
SummaryDependencyVersions

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
filter (element: Element) => boolean if provided, only elements for which the function returns true will be highlighted and trigger callbacks
onCancel () => void callback fired when the user presses the Escape key to cancel picking; picking is stopped automatically

Scroll & resize: While picking is active, the overlay automatically repositions itself when the page is scrolled or the window is resized.

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

Properties:

  • isPicking (readonly boolean) - true while the picker is active, false otherwise

Methods:

  • startPicking() - start picking elements
  • stopPicking() - stop picking elements
  • destroy() - permanently tear down the picker: stops picking, removes the overlay element from the DOM, and prevents any further use

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

Keywords

elementpickpickerwebbrowserDOMJavaScriptTypeScriptcustomization