js-element-picker v0.2.0
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 elementsstopPicking()
- 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}`),
});