{"id":13630726,"url":"https://github.com/ethanselzer/react-cursor-position","last_synced_at":"2025-04-17T17:31:38.708Z","repository":{"id":48121703,"uuid":"65648668","full_name":"ethanselzer/react-cursor-position","owner":"ethanselzer","description":"A React component that decorates its children with mouse and touch coordinates relative to itself.","archived":false,"fork":false,"pushed_at":"2024-02-19T13:14:03.000Z","size":5380,"stargazers_count":143,"open_issues_count":22,"forks_count":35,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-09T19:40:26.265Z","etag":null,"topics":["coordinates","cursor","detect","drag","follow","listener","monitior","mouse","mousemove","observer","pan","point","position","react","tap","touch","touchmove","track"],"latest_commit_sha":null,"homepage":"https://ethanselzer.github.io/react-cursor-position","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/ethanselzer.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":"2016-08-14T03:45:15.000Z","updated_at":"2024-04-16T20:33:22.000Z","dependencies_parsed_at":"2024-06-14T00:45:28.665Z","dependency_job_id":"b4019bc5-22f9-4707-abb0-9858a76742dc","html_url":"https://github.com/ethanselzer/react-cursor-position","commit_stats":{"total_commits":89,"total_committers":3,"mean_commits":"29.666666666666668","dds":0.0561797752808989,"last_synced_commit":"0f594bb6f08e774c68ef131d883ece1a55823ad0"},"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethanselzer%2Freact-cursor-position","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethanselzer%2Freact-cursor-position/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethanselzer%2Freact-cursor-position/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethanselzer%2Freact-cursor-position/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ethanselzer","download_url":"https://codeload.github.com/ethanselzer/react-cursor-position/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249200082,"owners_count":21228995,"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":["coordinates","cursor","detect","drag","follow","listener","monitior","mouse","mousemove","observer","pan","point","position","react","tap","touch","touchmove","track"],"created_at":"2024-08-01T22:01:57.584Z","updated_at":"2025-04-17T17:31:38.317Z","avatar_url":"https://github.com/ethanselzer.png","language":"JavaScript","readme":"# react-cursor-position\nreact-cursor-position is a primitive component for composing UI features that require notification of cursor or touch position changes. Position coordinates are plotted relative to the HTML element rendered by react-cursor-position. react-cursor-position re-renders child components with new position props when the cursor or touch position changes.\n\n* May be activated by Press, Tap, Touch, Hover and Click gestures\n* Supports scroll position changes during an active session\n\n\n\n## Status\n\n[![CircleCI](https://img.shields.io/circleci/project/github/ethanselzer/react-cursor-position.svg)](https://circleci.com/gh/ethanselzer/react-cursor-position)\n[![Coverage Status](https://coveralls.io/repos/github/ethanselzer/react-cursor-position/badge.svg?branch=master)](https://coveralls.io/github/ethanselzer/react-cursor-position?branch=master)\n[![npm](https://img.shields.io/npm/v/react-cursor-position.svg)](https://www.npmjs.com/package/react-cursor-position)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\n## Demo\n\nSee the [react-cursor-position demo site](https://ethanselzer.github.io/react-cursor-position).\n\nExperiment with react-cursor-position [live on CodePen](http://codepen.io/ethanselzer/pen/ryayLK).\n\n## Installation\n\n```sh\nnpm install --save react-cursor-position\n```\n\n## Usage\n\nIf you are upgrading from v2x to v3x please see [the release notes](https://github.com/ethanselzer/react-cursor-position/releases/tag/v3.0.0)\n\nIf you are upgrading from v1x to v2x please see [the release notes](https://github.com/ethanselzer/react-cursor-position/releases/tag/v2.0.0).\n\n```JSX\nimport ReactCursorPosition from 'react-cursor-position';\n...\n\n\u003cReactCursorPosition\u003e\n    \u003cYourComponentOne/\u003e\n    \u003cYourComponentTwo/\u003e\n\u003c/ReactCursorPosition\u003e\n```\n\nreact-cursor-position wraps its children in a div, which mouse and touch position\nare plotted relative to.\n\nEach child component will receive the following props:\n\n```JavaScript\n{\n    detectedEnvironment: {\n        isMouseDetected: false,\n        isTouchDetected: false,\n    },\n    elementDimensions: {\n        width: Number,\n        height: Number\n    },\n    isActive: Boolean,\n    isPositionOutside: Boolean,\n    position: {\n        x: Number,\n        y: Number\n    }\n}\n```\nThis structure may be customized by implementing `mapChildProps` API feature.\n\nThe information in `detectedEnvironment` is acquired from interaction with this component and will be unset until the first interaction.\n\n## Props API\n\nAll props are optional.\n\n**activationInteractionMouse** : String - One of INTERACTIONS.HOVER (default), INTERACTIONS.CLICK. Import Interactions like this `import ReactCursorPosition, { Interactions } from 'react-cursor-position'`. See [examples](https://ethanselzer.github.io/react-cursor-position/#/activate-by-hover). for more.\n\n**activationInteractionTouch** : String - One of INTERACTIONS.PRESS (default), INTERACTIONS.TAP, or INTERACTIONS.TOUCH. Import Interactions like this `import ReactCursorPosition, { Interactions } from 'react-cursor-position'`. See [examples](https://ethanselzer.github.io/react-cursor-position/#/activate-by-press).\n\n**className** : String - CSS class name(s) to be applied to the div rendered by react-cursor-position.\n\n**hoverDelayInMs** : Number - Amount of time, in milliseconds, to delay hover interaction from activating. Defaults to 0.\n\n**hoverOffDelayInMs** : Number - Amount of time, in milliseconds, to delay hover off interaciton from deactivating. Defaults to 0.\n\n**isEnabled** : Boolean - Enable or disable cursor position monitoring without remounting. Defaults to true.\n\n**mapChildProps** : Function - Model child component props to your custom shape.\nFunction receives one parameter with the signature\n`{ isActive: Boolean, isPositionOutside: Boolean, position: { x: Number, y: Number } }`.  \nIt should return an object that is compatible with the props interface of your child components.\nSee [example demo](https://ethanselzer.github.io/react-cursor-position/#/map-child-props).\n\n**onActivationChanged** : Function - Called when the component is active.\nFunction receives one parameter with the signature `{ isActive: Boolean }`.\n\n**onPositionChanged** : Function - Called when cursor or touch position changes.\nFunction receives one parameter with the signature `{ elementDimensions: { width: Number, height: Number }, isPositionOutside: Boolean, position: { x: Number, y: Number } }`.\n\n**onDetectedEnvironmentChanged** : Function - Called when detected environment (mouse or touch) changes.\nFunction receives one parameter with the signature `{ isMouseDetected: Boolean, isTouchDetected: Boolean }`.\n\n**pressDurationInMs** : Number - Milliseconds delay before press gesture is activated. Defaults to 500.\n\n**pressMoveThreshold** : Number - Amount of movement, in pixels, allowed during press gesture detection. Defaults to 5.\n\n**shouldDecorateChildren** : Boolean - Suppress decoration of child components by\nsetting this prop false. Defaults to true.\n\n**shouldStopTouchMovePropagation** : Boolean - Stop touchmove event bubbling when react-cursor-position is active. Defaults to false.\n\n**style** : Object - Style to be applied to the div rendered by react-cursor-position.\n\n**tapDurationInMs** : Number - Max milliseconds allowed for a screen touch to be considered a tap gesture. Defaults to 180.\n\n**tapMoveThreshold** : Number - Amount of movement, in pixels, allowed during tap gesture detection. Defaults to 5.\n\n## Imperative API\n**reset**: Invoking the reset method instructs react-cursor-position to recalculate its position relative to the page.\n\nSee API Examples section of the [demo site](https://ethanselzer.github.io/react-cursor-position/#/) for more.\n\n## Support\n\nPlease [open an issue](https://github.com/ethanselzer/react-cursor-position/issues).\n\n## Example Project\n\n```ssh\ngit clone https://github.com/ethanselzer/react-cursor-position.git\ncd react-cursor-position\nnpm install\nnpm run build\ncd example\nyarn\nyarn start\n```\n\nIf your default browser does not start automatically, open a new browser window and go to localhost:3000\n\n## Development\n\n```ssh\ngit clone https://github.com/ethanselzer/react-cursor-position.git\ncd react-cursor-position\nnpm install\nnpm run #print available commands\n```\nThe Example Project may be used in development of react-cursor-position. \n\nTo rebuild the source automatically when changes are made, run `npm run build-watch`.\n\n## Contributing\n\nPlease contribute by [opening an issue](https://github.com/ethanselzer/react-cursor-position/issues)\nor a [pull request](https://github.com/ethanselzer/react-cursor-position/compare/).\n\n## Attribution\n\nThanks to the following community members for opening GitHub Issues and Pull Requests. Your input is very much appreciated!\n* @pr0digy\n* @JunyuanZheng\n* @chrisdrackett\n* @damien916  \n* @AlexMeah\n* @bdefore  \n* @webdobe  \n* @renchap  \n* @Slapbox  \n* @heyellieday\n* @Secretmapper  \n* @tekbreak  \n* @jacekradko\n\nYou are awesome! ✨💫\n\n## License\n\nMIT\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethanselzer%2Freact-cursor-position","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fethanselzer%2Freact-cursor-position","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethanselzer%2Freact-cursor-position/lists"}