{"id":21384596,"url":"https://github.com/jashgopani/cursor-nearby-elements","last_synced_at":"2025-07-27T09:42:31.144Z","repository":{"id":160347269,"uuid":"364008104","full_name":"jashgopani/cursor-nearby-elements","owner":"jashgopani","description":"A tiny package that helps you find DOM elements near the cursor position","archived":false,"fork":false,"pushed_at":"2023-01-27T13:52:30.000Z","size":105,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-09T23:29:48.304Z","etag":null,"topics":["cursor","cursor-position","dom","dom-elements","html","javascript","js","mouse-events","nearby-elements","npm","npm-package","radius"],"latest_commit_sha":null,"homepage":"http://jashgopani.github.io/cursor-nearby-elements","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jashgopani.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-03T17:26:59.000Z","updated_at":"2024-07-30T17:45:03.000Z","dependencies_parsed_at":null,"dependency_job_id":"3db893c4-dacf-4e59-9731-dcfbb80b7771","html_url":"https://github.com/jashgopani/cursor-nearby-elements","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jashgopani/cursor-nearby-elements","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jashgopani%2Fcursor-nearby-elements","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jashgopani%2Fcursor-nearby-elements/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jashgopani%2Fcursor-nearby-elements/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jashgopani%2Fcursor-nearby-elements/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jashgopani","download_url":"https://codeload.github.com/jashgopani/cursor-nearby-elements/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jashgopani%2Fcursor-nearby-elements/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265155713,"owners_count":23719567,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cursor","cursor-position","dom","dom-elements","html","javascript","js","mouse-events","nearby-elements","npm","npm-package","radius"],"created_at":"2024-11-22T11:42:09.885Z","updated_at":"2025-07-13T14:31:36.004Z","avatar_url":"https://github.com/jashgopani.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cursor-nearby-elements\n\n## This package helps you find elements near cursor position\n\n![Visitors](https://visitor-badge.glitch.me/badge?page_id=jashgopani.cursor-nearby-elements)\n[![GitHub issues](https://img.shields.io/github/issues/jashgopani/cursor-nearby-elements)](https://github.com/jashgopani/cursor-nearby-elements/issues) \n[![GitHub forks](https://img.shields.io/github/forks/jashgopani/cursor-nearby-elements)](https://github.com/jashgopani/cursor-nearby-elements/network) \n[![GitHub stars](https://img.shields.io/github/stars/jashgopani/cursor-nearby-elements)](https://github.com/jashgopani/cursor-nearby-elements/stargazers) \n[![GitHub license](https://img.shields.io/github/license/jashgopani/cursor-nearby-elements)](https://github.com/jashgopani/cursor-nearby-elements/blob/main/LICENSE)\n\n# Table of contents\n\n- [Features](#features)\n- [Changelog](#changelog)\n- [Installation](#installation)\n- [Getting Started](#getting-started)\n  - [Visual representation of the parameters](#visual-representation-of-the-parameters)\n  - [_nearbyElements ([directions,offset])_](#nearbyelements-directionsoffset)\n  - [_nearby (event, [ predicate, modifier, offsetPoints, shouldSkipAngle ])_](#nearby-event--predicate-modifier-offsetpoints-shouldskipangle-)\n- [Example](#example)\n- [Extras](#extras)\n\n### Changelog\n\n* @3.2.1 - bundled code and nearbyElements is not a default export\n* @3.1.1 - initial stable version\n  \n### Features\n\n- Find all elements near the cursor.\n- Filter the nearby elements based on some conditions.\n- Modify the nearby elements i.e change styles / innerHTML without iterating over them seperately\n- Fine tune the searching process by changing the number of directions, number of points in each direction and radius of the region around cursor.\n\n### Installation\n\n```\nnpm i cursor-nearby-elements\n```\n\n### Getting Started\n\nImport the method using `import` syntax and save the output of `nearbyElements` method in some variable.\n\n```javascript\nimport {nearbyElements} from cursor-nearby-elements;\nconst nearby = nearbyElements();\n```\n\n#### Visual representation of the parameters\n\n![Multiple points on radius](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/dumqs1k2xh1uuh1z9y5i.png)\n\n\u003e **_Note:_** Arguments inside _[ ]_ are optional\n\n#### _nearbyElements ([directions,offset])_\n\nThis method helps you to set the parameters for calculations that are carried out for finding nearby elements\n\n- ##### Arguments\n  - **directions:** The number of directions around the cursor to look for elements. ( \\*Default value is **8\\*** )(_no. of green radius lines in the fig above_)\n  - **offset:** The radius of the region around the cursor. Elements falling within this radius will be captured ( \\*Default value is **69\\*** )(_the value of radius itself in the fig above_)\n- ##### Returns\n  - **nearby Method:** This function is responsible for returning the elements nearby. Read below for detailed explanation.\n\n#### _nearby (event, [ predicate, modifier, offsetPoints, shouldSkipAngle ])_\n\nThis method takes an `event` object as a mandatory argument and returns an `Array of DOM Elements`\n\n- ##### Arguments\n  - **event:** Event object which is received in event handler\n  - **predicate:** This is a **function** that checks the DOM elements for specific condition and based on the return value, the elements is either added to the final array or discarded. _This method should strictly return boolean value_. `true` denotes that element will be selected else discarded.\n  - **modifier** This is a **function** that modifies the original DOM Element and returns the modified DOM elements. Modifications can be anything; you can think of this as a `map function` for DOM Element\n  - **offsetPoints** This is an **array of fractions** where each fraction is a position on the radius line (The green dots in the figure below). These are the points where the code will check for elements. By default, the fraction is **1** i.e the points on circumference of the red region. When passing the array, make sure to include all the positions you want to check for between 0 - the cursor position up to 1 - The point at offset distance inclusive.(_green dots on each radius/direction line; 0.25 and 1 in the fig above_)\n  - **shouldSkipAngle:** This is also a function that gets 2 arguments ; `angle (in radians) , index`. The index is the index of the array containing angle values. You can skip some angles (directions indirectly) based on some conditions based on angle value or index value ; while checking for elements. Return true if you want to skip the angle else false.\n- ##### Returns\n  - **Array:** Array of nearby DOM Elements\n\n### Example\n\nnearby function\n\n```javascript\nfunction handleMouseMove(e) {\n  //filtering nearby elements since I don't want my container element to be returned as nearby element\n  //I only want elements with class targets\n  const predicate = (el) =\u003e {\n    return !el.classList.contains(\"App\") \u0026\u0026 el.classList.contains(\"targets\");\n  };\n\n  //null checks are already present so you won't get null or undefined elements\n  const modifier = (el) =\u003e {\n    if (el.style) el.style.backgroundColor = \"red\";\n    return el;\n  };\n\n  //you can scale your region by providing a larger fraction for offset also\n  const offsetPoints = [0, 0.25, 0.5, 0.75, 1, 1.215];\n\n  //skip points on X and Y axis\n  const shouldSkipAngle = (rad, index) =\u003e {\n    return index % 2 === 0;\n  };\n\n  //all the args except event object are optional\n  const myelements = nearby(\n    e,\n    predicate,\n    modifier,\n    offsetPoints,\n    shouldSkipAngle\n  );\n}\n```\n\n### Extras\n\n**1. If you are using framework like react:**\nYou should not modify DOM elements directly, you must change `state` or use `ref`s. Since this package returns a DOM element object, what you can do is store the `ref` of all the target elements in a dictionary/map like object with key as `stringify` version of `ref` and value as the `ref` object itself using [react-ref-compare](https://www.npmjs.com/package/react-ref-compare) package.\n\n**2. I have a codesandbox setup for testing and demo of the package, you can playaround with the code there to get a better understanding of the package**\n\n[![cursor-nearby-elements DEMO](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/cursor-nearby-elements-demo-36tvn?autoresize=1\u0026fontsize=14\u0026hidenavigation=1\u0026theme=dark\u0026view=preview)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjashgopani%2Fcursor-nearby-elements","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjashgopani%2Fcursor-nearby-elements","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjashgopani%2Fcursor-nearby-elements/lists"}