{"id":13426681,"url":"https://github.com/williamngan/roll","last_synced_at":"2025-04-12T20:47:23.339Z","repository":{"id":38709347,"uuid":"43630725","full_name":"williamngan/roll","owner":"williamngan","description":"roll and scroll tracking -- a tiny javascript library","archived":false,"fork":false,"pushed_at":"2017-04-28T05:38:39.000Z","size":1478,"stargazers_count":1011,"open_issues_count":5,"forks_count":64,"subscribers_count":30,"default_branch":"master","last_synced_at":"2025-04-04T02:42:34.823Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/williamngan.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}},"created_at":"2015-10-04T09:04:21.000Z","updated_at":"2025-02-13T16:40:52.000Z","dependencies_parsed_at":"2022-09-14T02:51:03.282Z","dependency_job_id":null,"html_url":"https://github.com/williamngan/roll","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamngan%2Froll","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamngan%2Froll/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamngan%2Froll/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamngan%2Froll/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/williamngan","download_url":"https://codeload.github.com/williamngan/roll/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248631718,"owners_count":21136559,"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":[],"created_at":"2024-07-31T00:01:41.125Z","updated_at":"2025-04-12T20:47:23.309Z","avatar_url":"https://github.com/williamngan.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# roll.js\n\n![roll.js demo](http://williamngan.github.io/roll/demo/images/demo.png)\n\nA little js library (~8kb min, 3kb gzip, no dependencies) to help you keep track of position, scrolling, and pagination.\nNothing too fancy, but since I couldn't find a suitable library for these purposes, I made one for a friend and myself and you too!\nPing me [@williamngan](http://twitter.com/williamngan) if you have questions or comments.\n\n## Demo\nHere's a **[DOM scrolling demo](http://williamngan.github.io/roll/demo/index.html)** (with some weird iPhone paintings :satisfied:)\n\nHere's a **[Canvas demo](http://williamngan.github.io/roll/demo/canvas.html)**\n\n## Basic Usage\n\nSimply create a new instance, specifying the viewport size (500px in this example).\n\n`var roll = new Roll( 500 );`\n\nNext, add a couple of *steps* to the roll instance. You may use the static helper `Roll.chunk( stepSize, padding )` to create a step object.\n\n```javascript\nroll.addStep( Roll.chunk(500, 20) ); // Add a step of 500px with 20px padding\nroll.addStep( Roll.chunk(700, 20) );  // Add a step of 700px with 20px padding\n```\n\nWhen the pane is moved, usually via the function `roll.move( position )`,\nthe roll instance will emit a `roll` event and possibly a `step` event.\nYou can listen to these events in the usual manner. (see [EventEmitter docs](https://nodejs.org/api/events.html) ). For example,\n```javascript\nroll.on( \"roll\", function(step, currProgress, currPosition, totalProgress) {\n    // implement your logic here\n})\n\nroll.on( \"step\", function(curr, last) {\n    // implement your logic here\n})\n```\n\n## DOM Usage\n\nA common usage is to keep track of scrolling in a DOM element, and then do pagination or animation based on scroll position.\n\nThere are a couple of static helpers to simplify this task. First, create a `roll` instance using `Roll.DOM( viewportID, scrollpaneID, stepsID, stepClass, padding)`. For example,\n\n```javascript\nvar roll = Roll.DOM(\"#viewport\", \"#pane\", \"#steps\", \".step\", 100 );\n```\n\nThe html structure for a *scrolling slideshow* may look like this. Also see a [sample css](https://github.com/williamngan/roll/blob/master/demo/css/demo.css) that corresponds to that html.\n\n```html\n\u003cdiv id=\"roll\"\u003e\n\t\u003cdiv id=\"steps\"\u003e\n\t\t\u003cdiv id=\"s0\" class=\"step\"\u003eHello\u003c/div\u003e\n\t\t\u003cdiv id=\"s1\" class=\"step\"\u003eWorld\u003c/div\u003e\n\t\t\u003cdiv id=\"s2\" class=\"step\"\u003eHow's it going\u003c/div\u003e\n\t\u003c/div\u003e\n\t\u003cdiv id=\"viewport\"\u003e\n\t\t\u003cdiv id=\"pane\"\u003e\u003c/div\u003e\n\t\u003c/div\u003e\n\u003c/div\u003e\n```\n\nThen this will keep track of vertical scrolling in the #viewport DOM element. You can then listen for the `roll` and `step` events as shown in Basic Usage, and implement your own logic.\n\nOne more thing: `Roll.stepHandler(...)` is a helper to go through a slideshow with `step` event. It will add css classes to the `.step` elements based on which step is in view.\n\n```javascript\nroll.on( \"step\", Roll.stepHandler( roll, views, \"prev\", \"next\", \"curr\", true ) );\n```\n\nIn the above snippet, `roll` is the roll instance, `views` is an array of the .step DOM elements, and `\"prev\", \"next\" \"curr\"` are css class names to assign to previous, next, and current step elements.\n\nA good way to get started is to take a look at the demos above, and then check out the source code in [demo folder](https://github.com/williamngan/roll/tree/master/demo).\n\n## Compiling\n\nThis library is written in javascript ES6 and compiled with Babel. If you want to change the source code and rebuild, simply `npm install` to get the dev dependencies,\nand then run `gulp` to watch and build.\n\n## NPM\n[https://www.npmjs.com/package/rolljs](https://www.npmjs.com/package/rolljs) \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilliamngan%2Froll","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwilliamngan%2Froll","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilliamngan%2Froll/lists"}