{"id":17786714,"url":"https://github.com/adasha/proximity-effect","last_synced_at":"2025-03-16T06:33:08.065Z","repository":{"id":37484244,"uuid":"139058062","full_name":"Adasha/proximity-effect","owner":"Adasha","description":"Mass animate CSS properties based on mouse or other target's position.","archived":false,"fork":false,"pushed_at":"2023-01-08T16:46:59.000Z","size":1960,"stargazers_count":8,"open_issues_count":5,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-08T00:42:18.144Z","etag":null,"topics":["animate","animation","approach","closeness","css","distance","effect","eye-candy","fader","filter","interpolation","mouse","nearness","proximity","style","transform","transition","visual"],"latest_commit_sha":null,"homepage":"http://lab.adasha.com/components/proximity-effect","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Adasha.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-06-28T19:04:24.000Z","updated_at":"2023-07-19T08:16:59.000Z","dependencies_parsed_at":"2023-02-08T06:45:33.832Z","dependency_job_id":null,"html_url":"https://github.com/Adasha/proximity-effect","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Adasha%2Fproximity-effect","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Adasha%2Fproximity-effect/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Adasha%2Fproximity-effect/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Adasha%2Fproximity-effect/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Adasha","download_url":"https://codeload.github.com/Adasha/proximity-effect/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221661157,"owners_count":16859489,"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":["animate","animation","approach","closeness","css","distance","effect","eye-candy","fader","filter","interpolation","mouse","nearness","proximity","style","transform","transition","visual"],"created_at":"2024-10-27T10:04:35.091Z","updated_at":"2024-10-27T10:04:35.747Z","avatar_url":"https://github.com/Adasha.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ProximityEffect.js\n\nv3.0.0-a4\n\nBulk modify CSS properties on elements based on mouse pointer or other arbitrary element proximity. Very customisable, definitely overdeveloped. A fun pet project originally from the Flash days, remade in JS as a practice project. Version 3 has had an API makeover and is a little more flexible. More importantly, it can be a LOT more flexible in the future, and shouldn't see any more drastic changes to the syntax (he says naively). \n\n[View live demos](http://lab.adasha.com/components/proximity-effect)\n\n## Roadmap\n\n- (for 3.0) Fix up code. Stable API. Better documentation.\n- (for 3.1) Multiple-value CSS properties.\n- (for 3.2) Per-property parameters.\n- (for 3.3) Multi-point animations.\n\n## Installation\n\n### Vanilla\n\nLatest ES6+ version is in `src`, ES5/minified versions are in `dist`. Download your version of choice and embed in your HTML:\n```html\n\u003cscript src=\"ProximityEffect.min.js\"\u003e\u003c/script\u003e\n```\n\n### CDN\n\n```html\n\u003cscript src=\"https://unpkg.com/proximity-effect\"\u003e\u003c/script\u003e\n```\n\n## Use\n\n### Add some content to affect\n\nIn your `\u003cbody\u003e` content add some elements you want to affect:\n\n```html\n\u003cdiv\u003e\n   \u003cdiv class=\"foo\"\u003e...\u003c/div\u003e\n   \u003cdiv class=\"foo\"\u003e...\u003c/div\u003e\n   \u003cdiv class=\"foo\"\u003e...\u003c/div\u003e\n   ...\n\u003c/div\u003e\n```\n\nYou could also generate some elements programmatically.\n\n### Set-up\n\nRemaining set-up should be done after content has loaded. Start by defining your list of `elements` to animate, and `params` object to control the animation.\n\n#### Elements\n\nProximityEffect needs a NodeList containing all the elements to include. You can use any suitable DOM method for this, e.g.:\n\n```javascript\nlet elements = document.querySelectorAll(\"*.foo\");\n```\n\n#### Params\n\nNext, define the effect parameters in an object. All parameters are optional, but without setting at least a value for `threshold` or `runoff` you won't see anything. Nearly all parameters can also be accessed as properties after instantiation.\n\n| Parameter | Type | Details |\n| :---: | :---: | :--- |\n| `attack` and `decay` | Number | Sets the rate of change when approaching (`attack`) or receding (`decay`), giving an effect of inertia. 1 is full speed,  0 is no movement (effectively disabling the animation). Default is 1. |\n| `invert` | Boolean | Reverse the `keyframes` array, effectively swapping near and far distances. Default is `false`. |\n| `threshold` | Number | The minimum distance (from element's mathematical centre) before effect starts, in pixels. Can be any positive number, default is 0. |\n| `runoff` | Number | The distance over which styles are interpolated, in pixels. Default is 0. |\n| `direction` | String | The coordinates axis/axes to use for distance calculations. Can be `\"both\"`, `\"horizontal\"` or `\"vertical\"`. Default is `\"both\"`. |\n| `offsetX` and `offsetY` | Number | Global horizontal (`offsetX`) and vertical (`offsetY`) centre-point offset. Default is 0. Stacks with individual element offsets. |\n| `jitter`, `jitterX` and `jitterY` | Number | Random offset per element, in pixels. `jitter` affects both X and Y values, while `jitterX` and `jitterY` affect only their respective axis. All three values stack. Default is 0. |\n| `jitterMethod` | String | Random generation method for jitter values. Accepts `\"uniform\"` or `\"gaussian\"`. Default is `\"uniform\"`. |\n| `FPS` | Number or Falsy | If set to a positive number, will attempt to refresh any effects at the specified frame rate. Effect updates cannot be displayed quicker than your screen's refresh rate, but internal calculations can take place more quickly. Specifying any value that is not a positive number, or no value at all, will clear the FPS property and attempt to refresh at the screen's refresh rate. |\n| `primeDistances` | Boolean | If `true`, will initialise all distances to 0, so the effect will appear to spring into its starting position. Can only be set as part of the `params` object during instantiation - it cannot be accessed as a property. |\n\nFor example:\n\n```javascript\nlet params = {\n   attack:     0.8,\n   decay:      0.7,\n   threshold: 40,\n   runoff:   100,\n   jitter:    35\n}\n```\n\n### Create a new ProximityEffect instance\n\nNext, create a ProximityEffect instance, feeding in the list of elements and the effect parameters:\n\n```javascript\nlet myEffect = new ProximityEffect(elements, params);\n```\n\nThe `params` object is optional - individual properties on the ProximityEffect instance can also be set after-the-fact, e.g.:\n\n```javascript\nmyEffect.runoff = 250;\nmyEffect.invert = true;\n```\n\n### Add style rules\n\nFinally, add style rules to the ProximityEffect instance as you see fit. The `addStyle()` method is used for this:\n\n```javascript\nProximityEffect.addStyle (property, keyframes, [params]);\n```\n\nHere's how the arguments break down:\n\n| Argument | Type | Description |\n| :---: | :---: | :--- |\n| `property` | String or Object | Defines the CSS property that will be modified. This can be a string that is the name of a [pre-defined CSS property](https://github.com/Adasha/proximity-effect/wiki/API-reference#supported-effects), or can be an object defining a property of your own. [details to come] |\n| `keyframes` | Array | An array defining the start and end values of this property when animated. Only the first and last values of the array are read currently; eventually more fine-grained animations will be possible. Values can be either a number specifying the value, or can be an object defining additional parameters. [details to come] |\n| `params` | Object | Currently unused. |\n\nProximityEffect comes pre-defined with [most permitted functions](https://github.com/Adasha/proximity-effect/wiki/API-reference#supported-effects) of the `transform` and `filter` style rules. It currently only supports custom properties with single numerical values in them, so rgb() and the like can't be used yet.\n\nFor example:\n\n```javascript\nmyEffect.addStyle('opacity', [100, 50]);\nmyEffect.addStyle('scale',   [  1,  2]);\nmyEffect.addStyle('blur',    [  0, 10]);\n```\n\nHere are some example of defining custom properties:\n\n```javascript\nmyEffect.addStyle({rule: 'left', unit: 'em'}, [100, 50]);\nmyEffect.addStyle({rule: 'transform', func: 'perspective', unit: 'px'},  [100, 50]);\n```\n\nThe `values` array can also contain objects with a `value` key and other optional properties, including a `scatter` value:\n\n```javascript\nmyEffect.addStyle('translateX', [0, {value: 50, scatter: 15}]);\nmyEffect.addStyle({rule: 'padding', unit: 'px'}, [{value: 20, scatter: 30}, {value: 100, scatter: 50}]);\n```\n\n## API\n\nFull details on the API are forthcoming, for now there is only an unfinished [page on the wiki](https://github.com/Adasha/proximity-effect/wiki/API-reference).\n\n\n\n## License:\n\nThis software is provided under the Mozilla Public License 2.0. You can freely use the code in your own projects, using any license, without limitation, but if you modify the code base those changes must be pushed back under the same MPL2 license. Any copyright/credits must be left intact.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadasha%2Fproximity-effect","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadasha%2Fproximity-effect","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadasha%2Fproximity-effect/lists"}