Reusable element picker library for userscripts.
لا ينبغي أن لا يتم تثبيت هذا السكريت مباشرة. هو مكتبة لسكبتات لتشمل مع التوجيه الفوقية // @require https://update.greasyfork.org/scripts/589922/1893812/Element%20Picker.js
A DOM element selection library designed for Userscripts and browser extensions. It features a premium draggable interface, an advanced selector engine, interactive DOM traversal, and theme customization support.
id, data-attributes, and automatically calculates :nth-child).Alt to bypass invisible overlays and select the elements hidden underneath them..pickOnce() method.Ctrl+Shift+E) to enable or disable the picker.To use the library, call the global elementPicker(config) function and store the generated instance.
// Initializes with a global keyboard shortcut (optional)
const picker = elementPicker({
toggleHotkey: 'Ctrl+Shift+E'
});
If you just need the user to click an element and return the result, use pickOnce(). The interface closes automatically after the click.
async function captureImage() {
// Enables the picker allowing ONLY images
const element = await picker.pickOnce({ filter: 'img' });
console.log("Selected image:", element.src);
}
You can inject your own buttons into the floating bar. These buttons will appear when an element is "locked" (clicked).
const picker = elementPicker();
// Adds a custom button
const actionId = picker.addAction({
label: 'Extract Data',
primary: true, // Highlights the button
onClick: (el) => {
console.log("Extracted text:", el.innerText);
picker.disable(); // Closes the picker after the action
}
});
// Enables the picker with restrictions (optional)
picker.enable({
exclude: 'header, footer, .ads' // Ignores these elements
});
elementPicker(globalConfig)Creates a new picker instance.
globalConfig (Object):toggleHotkey (String): Shortcut to toggle the picker globally (e.g., 'Ctrl+Shift+E').enable(options)Enables the selection interface.
options (Object):filter (String): CSS selector. If defined, only elements that match this selector can be picked (e.g., 'div, a').exclude (String): CSS selector. Elements matching this will be ignored by the mouse.disable()Disables and hides the interface, removing the overlays from the screen.
toggle(options)Switches between enable() and disable().
pickOnce(options) -> Promise<Element>Enables the picker, waits for the user to click an element, disables the picker, and returns the element inside a Promise.
destroy()Completely removes the library from the page (deletes the UI from the Shadow DOM, clears global listeners, and empties all callbacks).
addAction(config) -> StringAdds a button to the bar when an element is selected. Returns a unique id.
config: { label: String, primary: Boolean, onClick: Function(Element) }removeAction(id)Removes a specific action using the id returned by addAction.
removeAllActions()Removes all custom injected buttons.
onSelect(callback) -> FunctionRegisters a function to be called every time an element is "locked" (clicked). Returns an unsubscribe function.
const unsub = picker.onSelect((el) => console.log(el));
// unsub(); // Stops listening
isEnabled() -> BooleanReturns true if the selection interface is currently active.
getHoveredElement() -> Element | nullReturns the element currently under the mouse cursor.
getSelectedElement() -> Element | nullReturns the currently locked (clicked) element.
setSelectedElement(element)Forces the selection/lock on a specific element via code. Triggers the onSelect callbacks.
setTheme(colors)Overrides the UI CSS variables. Colors must be valid CSS strings (Hex, RGB, HSL, etc.).
picker.setTheme({
primary: '#10B981', // Highlight color (green)
background: '#1F2937', // UI bar background
text: '#FFFFFF', // Main text color
highlightBorder: 'red', // Hover border color
});
Available properties: primary, background, text, textMuted, border, divider, pillBackground, highlightBorder, badgeBackground, badgeText, buttonBackground, buttonText.
When the Picker is enabled, the following shortcuts are available:
| Key | Action | Context |
|---|---|---|
Alt (Hold) |
X-Ray Mode: Bypasses overlays. Hides the hovered element to focus on what is underneath it. | Hovering |
Esc |
Disables the Element Picker (disable()). |
Always |
Click |
Locks/Unlocks the selection on the current element. | Hovering |
Arrows (↑ ↓ ← →) |
DOM Traversal: Navigates through the DOM tree starting from the locked element (Parent, First Child, Previous Sibling, Next Sibling). | Locked Element |
Developed by hdyzen. Designed for GreasyFork scripts. Feel free to report bugs, suggest performance improvements, or create forks to adapt it to your needs.