{"id":17621156,"url":"https://github.com/noeldelgado/pisces","last_synced_at":"2025-10-06T09:16:32.733Z","repository":{"id":57324894,"uuid":"59334940","full_name":"noeldelgado/pisces","owner":"noeldelgado","description":":wavy_dash: Scroll to specific locations of any scrolling box in a smooth fashion.","archived":false,"fork":false,"pushed_at":"2020-03-08T09:25:45.000Z","size":196,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-29T21:27:51.576Z","etag":null,"topics":["animation","scroll-to","scrolling","scrollingelement","scrollto","scrolltobottom","scrolltoelement","scrolltoposition","scrolltotop","smooth-scrolling"],"latest_commit_sha":null,"homepage":"https://noeldelgado.github.io/pisces/","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/noeldelgado.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-05-21T01:06:11.000Z","updated_at":"2020-03-08T09:25:47.000Z","dependencies_parsed_at":"2022-09-04T11:50:31.417Z","dependency_job_id":null,"html_url":"https://github.com/noeldelgado/pisces","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noeldelgado%2Fpisces","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noeldelgado%2Fpisces/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noeldelgado%2Fpisces/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noeldelgado%2Fpisces/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/noeldelgado","download_url":"https://codeload.github.com/noeldelgado/pisces/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246262600,"owners_count":20749175,"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":["animation","scroll-to","scrolling","scrollingelement","scrollto","scrolltobottom","scrolltoelement","scrolltoposition","scrolltotop","smooth-scrolling"],"created_at":"2024-10-22T20:11:34.641Z","updated_at":"2025-10-06T09:16:27.662Z","avatar_url":"https://github.com/noeldelgado.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pisces [![npm-image](https://img.shields.io/npm/v/pisces.svg)](https://www.npmjs.com/package/pisces) ![license-image](https://img.shields.io/npm/l/pisces.svg)\n\nScroll to specific locations of any scrolling box in a smooth fashion.\n\nhttps://noeldelgado.github.io/pisces/\n\n## Table of Contents\n* [Install](#install)\n* [Basic Usage](#usage)\n* [Polyfills](#polyfills)\n* [API](#api)\n  * [params](#api-params)\n  * [scrollTo](#piscesscrolltotarget-options)\n  * [scrollToElement](#piscesscrolltoelementdomelement-options)\n  * [scrollToPosition](#piscesscrolltopositioncoordinates-options)\n  * [scrollToTop](#piscesscrolltotopoptions)\n  * [scrollToRight](#piscesscrolltorightoptions)\n  * [scrollToBottom](#piscesscrolltobottomoptions)\n  * [scrollToLeft](#piscesscrolltoleftoptions)\n  * [set](#piscessetkey-value)\n  * [cancel](#piscescancel)\n  * [getElementOffset](#piscesgetelementoffsetdomelement)\n* [Examples](#examples)\n  * [Provide a different easing function](#provide-a-different-easing-function)\n  * [Override options per method call](#override-options-per-method-call)\n  * [Using it with gemini-scrollbar](#using-it-with-gemini-scrollbar)\n* [License](#license)\n\n## Install\n\n```sh\nnpm i pisces --save\n```\n\n\u003ch2 id=\"usage\"\u003eBasic Usage\u003c/h2\u003e\n\n```js\nimport Pisces from 'pisces';\n\nconst pisces = new Pisces();\n\npisces.scrollToElement(document.querySelector('.some-element'));\npisces.scrollToPosition({ y: 100 });\npisces.scrollToPosition({ x: '-10', y: '+300' });\npisces.scrollToBottom();\n```\n\n## Polyfills\n\nIf you need to support **IE9-** make sure to add the following polyfills:\n\n* requestAnimationFrame\n* cancelAnimationFrame\n* performance.now\n\n## API\n\n\u003ch3 id=\"api-params\"\u003ePisces([scrollingBox], [options])\u003c/h3\u003e\n\nConstructor. Creates a new Pisces instance (you should create a new instance per any different scrolling element you want to interact with).\n\n#### @param scrollingBox\n\nBecause of browser inconsistencies, if you want to scroll the default page (`window`, `document`, `body`), leave this option empty or pass `null` if you are passing additional `options`, [this module][get-scrollingelement] will try pick the right one for the current browser.\n\nIf you want to register any other scrolling element, you should pass a valid `DOMElement`.\n\n| type | default |\n|:-----|:--------|\n| `DOMElement` | `scrollingElement` or `documentElement` or `body` |\n\n#### @param options\n\n| name | type | default | description |\n|:-----|:-----|:--------|:------------|\n| duration | `Number` | 800 *(milliseconds)* |  How many milliseconds the animation should run for. |\n| easing | `Function` | `x =\u003e Math.sqrt(1-(--x*x))` | An easing function takes an `x` value, representing progress along a timeline (between 0 and 1), and returns a `y` value. |\n| onComplete | `Function` | `null` | The function to run the animation is completed. |\n\n### Methods\n### pisces.scrollTo(target, options)\n\nProxy for `scrollToElement` or `scrollToPosition`.\n\nThis method allows you to pass a querySelector string to scroll to a specific element (e.g. \".my-element\"). Or to pass a hash with `x` and/or `y` keys to scroll to absolute or relatives points of the scrolling box.\n\n*If you know what you are doing please use the adequate method instead, see the other methods below.*\n\n### pisces.scrollToElement(domElement, [options])\n\nScrolls to an existing element inside your scrollingBox.\n\n```js\npisces.scrollToElement(pisces.scrollingBox.querySelector('.footer'));\n```\n\nThe `domElement` param is required and should be valid `DOMElement`.\n\nIf you pass the `options` hash param, it will use those options just for that iteration without overriding its defaults.\n\n### pisces.scrollToPosition(coordinates, [options])\n\nScrolls to a specific `x`, `y` position of the scrollingBox. It can be a fixed value relative to the top/left coordinates or to relative values from the current position.\n\n```js\n// absolute\npisces.scrollToPosition({x: 100, y: 100});\n\n// relative\npisces.scrollToPosition({x: '+100', y: '-100'});\n\n// mixed\npisces.scrollToPosition({x: 100, y: '-100'});\n```\n\nThe `coordinates` params is required.\n\nIt should be a hash with an `x` and/or `y` key(s).\n\nIf you pass the `options` hash param, it will use those options just for that iteration without overriding its defaults.\n\n### pisces.scrollToTop([options])\n\nScrolls to the top position of the scrollingBox.\n\n```js\npisces.scrollToTop();\n```\n\nIf you pass the `options` hash param, it will use those options just for that iteration without overriding its defaults.\n\n### pisces.scrollToRight([options])\n\nScrolls to the far right position of the scrollingBox.\n\n```js\npisces.scrollToRight();\n```\n\nIf you pass the `options` hash param, it will use those options just for that iteration without overriding its defaults.\n\n### pisces.scrollToBottom([options])\n\nScrolls to the bottom position of the scrollingBox.\n\n```js\npisces.scrollToBottom();\n```\n\nIf you pass the `options` hash param, it will use those options just for that iteration without overriding its defaults.\n\n### pisces.scrollToLeft([options])\n\nScrolls to the far left position of the scrollingBox.\n\n```js\npisces.scrollToLeft();\n```\n\nIf you pass the `options` hash param, it will use those options just for that iteration without overriding its defaults.\n\n### pisces.set(key, value)\n\nOverrides the `options` set during instantiation.\n\n```js\npisces.set('duration', 200);\npisces.set('easing', someCustomEasingFunction);\npisces.set('onComplete', someFunctionToRunOnComplete);\n```\n\n### pisces.cancel()\n\nStops the animation loop.\n\n### pisces.getElementOffset(DOMElement)\n\nReturns a hash with the position of the passed `DOMElement` relative to the instance’s `scrollingBox` scroll position or `false` in case the `scrollingBox` does not contains the passed `DOMElement`.\n\nThis can be useful in cases where you have a fixed header (or some other fixed element) and you do not want to scroll underneath it.\n\nIn case the passed `DOMElement` is inside the instance’s `scrollingBox` it will return a hash with an `x` and `y` keys, e.g. `{ x: \u003cnumber\u003e, y: \u003cnumber\u003e }`, then you can use those values to call the `scrollToPosition` method subtracting your fixed element height/width.\n\n## Examples\n\n### Provide a different easing function\n\nIf you are not happy with the default easing function provided (`Circular.Out`) you can pass a custom function or use one provided from another library. \n\nRemember that an easing function should take an x value, representing progress along a timeline (between 0 and 1), and return a y value.\n\n```js\nimport Pisces from 'Pisces';\nimport tween from 'tween.js';\nimport eases from 'eases';\n\nconst piscesA = new Pisces(document.querySelector('.a'), {\n  easing: tween.Easing.Back.InOut,\n  duration: 1000\n});\n\nconst piscesB = new Pisces(document.querySelector('.b'), {\n  easing: eases.elasticInOut\n});\n\nconst piscesC = new Pisces(document.querySelector('.c'), {\n  easing: (x) =\u003e Math.sqrt(1-(--x*x))\n});\n```\n\n### Override options per method call\n\nIf you need it you can change the options every time you call a method. This will not override the default options, but the use them just for this call. This can be useful for debugging, changing the `duration` and `easing` to see which combination works better for you.\n\n```js\nimport Pisces from 'Pisces';\nimport tween from 'tween.js';\n\nconst pisces = new Pisces(document.querySelector('.scrollable'));\n...\npisces.scrollTo('.target', {\n  easing: tween.Easing.Quintic.In,\n  duration: 400\n});\n\n```\n\n### Using it with [gemini-scrollbar]\n\n```js\nimport Pisces from 'pisces';\nimport Gemini from 'gemini-scrollbar';\n\nconst gemini = new Gemini({\n  element: document.querySelector('.scrolling-box')\n}).create();\n\n/* the key part to make it compatible with gemini-scrollbar */\nconst pisces = new Pisces(gemini.getViewElement());\n\n/* simple example, check the available methods on the API section */\nconst coords = { x: 0, y: 200 };\npisces.scrollToPosition(coords);\n```\n\n## License\nMIT © [Noel Delgado](http://pixelia.me/)\n\n[gemini-scrollbar]: https://github.com/noeldelgado/gemini-scrollbar\n[get-scrollingelement]: https://github.com/noeldelgado/get-scrollingelement\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnoeldelgado%2Fpisces","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnoeldelgado%2Fpisces","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnoeldelgado%2Fpisces/lists"}