{"id":20280914,"url":"https://github.com/sjwilliams/scrollstory","last_synced_at":"2025-08-23T00:27:22.006Z","repository":{"id":12854411,"uuid":"15530381","full_name":"sjwilliams/scrollstory","owner":"sjwilliams","description":"A jQuery plugin for building scroll-based stories","archived":false,"fork":false,"pushed_at":"2022-02-12T03:00:06.000Z","size":1188,"stargazers_count":283,"open_issues_count":13,"forks_count":31,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-07-26T07:33:15.168Z","etag":null,"topics":["scroll-events","scrolling","scrollytelling","storytelling","trigger"],"latest_commit_sha":null,"homepage":"http://sjwilliams.github.io/scrollstory/","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/sjwilliams.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":"2013-12-30T15:22:59.000Z","updated_at":"2025-05-08T07:47:46.000Z","dependencies_parsed_at":"2022-09-12T06:11:47.303Z","dependency_job_id":null,"html_url":"https://github.com/sjwilliams/scrollstory","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/sjwilliams/scrollstory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjwilliams%2Fscrollstory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjwilliams%2Fscrollstory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjwilliams%2Fscrollstory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjwilliams%2Fscrollstory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sjwilliams","download_url":"https://codeload.github.com/sjwilliams/scrollstory/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjwilliams%2Fscrollstory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271723011,"owners_count":24809669,"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","status":"online","status_checked_at":"2025-08-22T02:00:08.480Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["scroll-events","scrolling","scrollytelling","storytelling","trigger"],"created_at":"2024-11-14T13:38:18.675Z","updated_at":"2025-08-23T00:27:21.955Z","avatar_url":"https://github.com/sjwilliams.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ScrollStory\n\nScrollStory is a jQuery plugin for building scroll-based stories. Rather than doing a specific task, it aims to be a tool to help solve general problems.\n\nFor example, it can help you **update your nav** as you scroll down the page. It can **auto-scroll** to sections of your story on a mouse click or custom event. It can trigger **custom callbacks** that manipulate the page as you scroll, like **lazy loading** media. It can dynamically insert markup into the page using an array of data on instantiation, or use pre-existing markup. Additionally, it **maintains data** associated with all these custom interactions.\n\n## Examples\n* Controlling scroll-based graphic in [111 N.F.L. Brains. All But One Had C.T.E.](https://www.nytimes.com/interactive/2017/07/25/sports/football/nfl-cte.html), nytimes.com\n* Triggering zoomy photo in [Fleeing Boko Haram, Thousands Cling to a Road to Nowhere](https://www.nytimes.com/interactive/2017/03/30/world/africa/the-road-to-nowhere-niger.html), nytimes.com\n* Triggering animations in the desktop version of [This Is Your Life, Brought to You by Private Equity](https://www.nytimes.com/interactive/2016/08/02/business/dealbook/this-is-your-life-private-equity.html), nytimes.com\n* ScrollStory compared in [How to implement scrollytelling with six different libraries](https://pudding.cool/process/how-to-implement-scrollytelling/demo/scrollstory/), pudding.cool\n* Lazy loading 360º video in [52 Places to Go in 2017](https://www.nytimes.com/interactive/2017/travel/places-to-visit.html), nytimes.com\n* Revealing text in [A Gift to New York, in Time for the Pope](http://www.nytimes.com/interactive/2015/09/17/nyregion/st-patricks-cathedral-pope-francis-visit.html), nytimes.com\n\n## Overview\n\nScrollStory is built on the idea that scrolling stories often comprise discrete elements stacked on a page that exclusively require a reader’s focus. These elements \u0026mdash; or `items` in ScrollStory speak \u0026mdash; can be anything: sections of text (like the sections of this page), a video, a photo and caption, or any HTML element that can be scrolled to.\n\nScrollStory follows these items, internally tracking the scroll distance until an item requires the reader’s focus, at which point custom code can be executed to manipulate the experience, like updating the navigation bar and fading the background color on this page. Additionally, custom code can be run whenever any `item` enters the viewport; any `item` within a ScrollStory collection is activated (or, inversely, when none are activated); when an item is `filtered`, a ScrollStory construct meaning it is no longer an active part of a collection; or any of **17 custom events**.\n\nScrollStory `items` aren't just DOM nodes. Rather, they’re data objects that have a corresponding representation in the DOM. ScrollStory instances maintain data about each `item` object in a collection and provides numerous methods of accessing, querying and modifying that data.\n\n\n## Documentation\n\n### Download\n* [Development](https://raw.githubusercontent.com/sjwilliams/scrollstory/master/dist/jquery.scrollstory.js)\n* [Production](https://raw.githubusercontent.com/sjwilliams/scrollstory/master/dist/jquery.scrollstory.min.js)\n* `npm install scrollstory`\n\n\n### Basic Usage\n\nIn its most basic form, ScrollStory takes a container element and searches for `.story` child elements. \n\n\n##### The code:\n\n```html\n\u003cbody\u003e\n  \u003c!-- Default markup style --\u003e\n  \u003cdiv id=\"container\"\u003e\n    \u003cdiv class=\"story\"\u003e\u003ch2\u003eStory 1\u003c/h2\u003e\u003cp\u003e...\u003c/p\u003e\u003c/div\u003e\n    \u003cdiv class=\"story\"\u003e\u003ch2\u003eStory 2\u003c/h2\u003e\u003cp\u003e...\u003c/p\u003e\u003c/div\u003e\n  \u003c/div\u003e\n  \n  \u003c!-- include jquery and scrollstory --\u003e\n  \u003cscript src=\"jquery.js\"\u003e\u003c/script\u003e\n  \u003cscript src=\"jquery.scrollstory.js\"\u003e\u003c/script\u003e\n  \n  \u003cscript\u003e\n    // Instantiation\n    $(function(){\n      $(\"#container\").scrollStory();\n    });\n  \u003c/script\u003e\n\u003c/body\u003e\n```\n\nInternally, ScrollStory turns those elements into `item` objects and assigns them several default properties, like its index position in the list, its `inViewport` status and a `data` object for user data.\n\n##### The item object:\n\n```js\n{\n  id: 'story0-2', // globally unique across every instance of ScrollStory. User-assigned or auto generated.\n  index: 0, // zero-based index for this item within this instance of ScrollStory\n  el: $(), // jQuery object containing the item node\n  data: {}, // user data for this item\n  inViewport: true,\n  fullyInViewport: false,\n  active: false, // is this the exclusively active item\n  filtered: false, // has this item been removed from the collection\n  category: 'people', // optional. single, top-level association.\n  tags: ['friend', 'relative'], // optional. array of strings defining lose relationships between items.\n  distanceToOffset: -589, // px distance to global trigger,\n  adjustedDistanceToOffet: -589, //px distance to trigger taking into account any local adjustments for this item\n  scrollStory: {}, // reference to the scrollstory instance this item belongs to\n  height: 582, // item element height\n  width: 1341, // item element width\n  scrollOffset: false, // a number if the scrollOffset for this item is different from the global one\n  triggerOffset: false // a number if the triggerOffset for this item is different from the global one\n}\n```\n\nIn addition to creating item objects on instantiation, ScrollStory modifies the DOM to reflect various states.\n\n* A class of `scrollStory` is added to the container element.\n* A class of `scrollStoryActive` is added to the container element if any item is active.\n* A class of `scrollStoryActiveItem-{itemId}` is added to the container element to reflect currently \"active\" item.\n* A class of `scrollStoryItem` is added to every item element.\n* A class of `active` is added to the currently active item element.\n* A class of `inviewport` is added to item elements partially or fully in the viewport.\n* An ID attribute is added to any story item element that didn't have one.\n\n##### Post-instantiation DOM\n\n```html\n\u003cdiv id=\"container\" class=\"scrollStory scrollStoryActive scrollStoryActiveItem-story0-0\"\u003e\n  \u003cdiv id=\"story0-0\" class=\"story scrollStoryItem inviewport active \"\u003e...\u003c/div\u003e\n  \u003cdiv id=\"story0-1\" class=\"story scrollStoryItem inviewport\"\u003e...\u003c/div\u003e\n  \u003cdiv id=\"story0-2\" class=\"story scrollStoryItem\"\u003e...\u003c/div\u003e\n  \u003cdiv id=\"story0-3\" class=\"story scrollStoryItem\"\u003e...\u003c/div\u003e\n\u003c/div\u003e\n```\n\n### Pass In Data Via Attributes\n\nData can be dynamically added to individual item objects by adding it as data attributes in markup. Combined with ScrollStory's API methods, some very dynamic applications can be built.\n\n##### The code:\n\n```html\n\u003cdiv id=\"container\"\u003e\n  \u003cdiv class=\"story\" data-organization=\"The New York Times\" data-founded=\"1851\"\u003e\u003c/div\u003e\n  \u003cdiv class=\"story\" data-organization=\"The Washington Post\" data-founded=\"1877\"\u003e\u003c/div\u003e\n  ...\n\u003c/div\u003e\n\u003cscript\u003e\n  $(function(){\n    $(\"#container\").scrollStory();\n  });\n\u003c/script\u003e\n```\n\nInternally, ScrollStory turns those elements into item objects and assigns them several default properties, like its index position in the list, its inViewport status and a data object for user data.\n\n##### The \u003cspan code\u003eitem\u003c/span\u003e objects:\n\n```js\n[{\n  id: 'story0-0',\n  index: 0\n  inViewport: true,\n  active: true,\n  ...\n  data: {\n    organization: \"The New York Times\",\n    founded: \"1851\"\n  }\n},{\n  id: 'story0-1',\n  index: 1\n  inViewport: false,\n  active: false,\n  ...\n  data: {\n    organization: \"The Washington Post\",\n    founded: \"1877\"\n  }\n}]\n```\n\n\n##### Post-instantiation\n\n```html\n\u003cdiv id=\"container\" class=\"scrollStory scrollStoryActive scrollStoryActiveItem-story0-0\"\u003e\n  \u003cdiv id=\"story0-0\" class=\"story scrollStoryItem inviewport active\" data-organization=\"The New York Times\" data-founded=\"1851\"\u003e...\u003c/div\u003e\n  \u003cdiv id=\"story0-1\" class=\"story scrollStoryItem\" data-organization=\"The Washington Post\" data-founded=\"1877\"\u003e...\u003c/div\u003e\n\u003c/div\u003e\n```\n\n### Build From Data\n\nA ScrollStory instance can be built with an array of data objects instead of markup, which will be used to generate all the ScrollStory items and elements on the page. The items array and rendered markup are idential to the example above.\n\n##### The Code\n\n```js\n$(function(){\n\n  // data\n  var newspapers=[{\n    organization: \"The New York Times\",\n    founded: \"1851\"\n  },{\n    organization: \"The Washington Post\",\n    founded: \"1877\"\n  }];\n\n  // pass in the data\n  $(\"#container\").scrollStory({content: newspapers});\n});\n```\n\n\n\n##### Post-instantiation DOM\n\n```html\n\u003cdiv id=\"container\" class=\"scrollStory scrollStoryActive scrollStoryActiveItem-story0-0\"\u003e\n  \u003cdiv id=\"story0-0\" class=\"story scrollStoryItem inviewport active\" data-organization=\"The New York Times\" data-founded=\"1851\"\u003e...\u003c/div\u003e\n  \u003cdiv id=\"story0-1\" class=\"story scrollStoryItem\" data-organization=\"The Washington Post\" data-founded=\"1877\"\u003e...\u003c/div\u003e\n\u003c/div\u003e\n```\n\n### Using Data\n\nItem data can be used in most ScrollStory events and callbacks. For example, you can to use the data to dynamically generate markup during instantiation.\n\n\n```js\n$(function(){\n  var newspapers=[{organization: \"The New York Times\", founded: \"1851\"},{organization: \"The Washington Post\", founded: \"1877\"}];\n\n  $(\"#container\").scrollStory({\n    content: newspapers,\n    itembuild: function(ev, item){\n      item.el.append(\"\u003ch2\u003e\"+item.data.organization+\"\u003c/h2\u003e\");\n    },\n    itemfocus: function(ev, item){\n      console.log(item.data.organization + \", founded in \" + item.data.founded + \", is now active!\");\n    }\n  });\n});\n```\n\n##### Post-instantiation DOM\n\n```html\n\u003cdiv id=\"container\" class=\"scrollStory scrollStoryActive scrollStoryActiveItem-story0-0\"\u003e\n  \u003cdiv id=\"story0-0\" class=\"story scrollStoryItem inviewport active\" data-organization=\"The New York Times\" data-founded=\"1851\"\u003e\n    \u003ch2\u003eThe New York Times\u003c/h2\u003e\n  \u003c/div\u003e\n  \u003cdiv id=\"story0-1\" class=\"story scrollStoryItem\" data-organization=\"The Washington Post\" data-founded=\"1877\"\u003e\n    \u003ch2\u003eThe Washington Post\u003c/h2\u003e\n  \u003c/div\u003e\n\u003c/div\u003e\n```\n\nYou could also, for example, manipulate the styles of items as they gain and lose focus. Here we'll interact with the same instance as before, but instead of callbacks we'll use events, which are available after instantiation.\n\n```js\n$(\"container\").on('itemfocus', function(item){\n  if(item.index === 0){\n    item.el.css('background-color', 'purple');\n  } else {\n    item.el.css('background-color', 'red');\n  }\n});\n\n$(\"container\").on('itemblur', function(ev, item){\n  item.el.css('background-color', 'white');\n});\n```\n\nAdmittedly this example is a bit contrived as we could have done the same thing in CSS alone:\n```css\n.story{\n  background-color: white;\n}\n\n.story.active{\n  background-color: red;\n}\n\n.scrollStoryActiveItem-story0-0 .story.active{\n  background-color: purple;\n}\n\n```\n\n### Instantiation Options\n\n#### content\nType: `jQuery Object`, `String`, or `array`\nDefault value: 'null'\n\n```js\n$('#container').scrollStory({\n    content: [{name:'Josh', town: 'San Francisco'}]\n});\n```\nIf given a jQuery object, class selector string, or array of values, use the cooresponding data to build items in this instance.\n\n#### contentSelector\nType: `String`\nDefault value: '.story'\n\n```js\n$('#container').scrollStory({\n    contentSelector: '.story'\n});\n```\nA jQuery selector to find story items within your widget.\n\n#### keyboard\nType: `Boolean`\nDefault value: true\n\n```js\n$('#container').scrollStory({\n    keyboard: true\n});\n```\nEnable left and right arrow keys to move between story items.\n\n#### triggerOffset\nType: `Number`\nDefault value: 0\n\n```js\n$('#container').scrollStory({\n    triggerOffset: 0\n});\n```\nThe trigger offset is the distance from the top of the page used to determine which item is active.\n\n\n#### scrollOffset\nType: `Number`\nDefault value: 0\n\n```js\n$('#container').scrollStory({\n    scrollOffset: 0\n});\n```\nWhen programatically scrolled, this is the position in pixels from the top the item is scrolled to.\n\n#### autoActivateFirstItem\nType: `Boolean`\n\nDefault value: false\n\n```js\n$('#container').scrollStory({\n    autoActivateFirstItem: false\n});\n```\nAutomatically activate the first item on page load, regardless of its position relative to the offset and the 'preOffsetActivation' setting. Common case: you want to disable 'preOffsetActivation' to ensure late scroll activations but need the first item to be enabled on load. With 'preOffsetActivation:true', this is ignored.\n\n#### disablePastLastItem\nType: `Boolean`\nDefault value: true\n\n```js\n$('#container').scrollStory({\n    disablePastLastItem: true\n});\n```\nDisable last item -- and the entire widget -- once the last item has scrolled beyond the trigger point.\n\n#### speed\nType: `Number`\n\nDefault value: 800\n\n```js\n$('#container').scrollStory({\n    speed: 800\n});\n```\nAutomated scroll speed in ms. Set to 0 to remove animation.\n\n#### easing\nType: `String`\n\nDefault value: 'swing'\n\n```js\n$('#container').scrollStory({\n    easing: 'swing'\n});\n```\nThe easing, 'swing' or 'linear', to use during programatic scrolls.  \n\n \n#### scrollSensitivity\nType: `Number`\n\nDefault value: 100\n\n```js\n$('#container').scrollStory({\n    scrollSensitivity: 100\n});\n```\nHow often in milliseconds to check for the active item during a scroll. Use a higher number if performance becomes an issue.\n\n#### throttleType\nType: `String`\n\nDefault value: 'debounce'\n\n```js\n$('#container').scrollStory({\n    throttleType: 'debounce' // debounce or throttle\n});\n```\nSet the throttle -- or rate-limiting -- method used when testing items' active state. These are wrappers around Underscore's [throttle](http://underscorejs.org/#throttle) and [debounce](http://underscorejs.org/#debounce) functions. Use 'throttle' to trigger active state on the leading edge of the scroll event. Use 'debounce' to trigger on the trailing edge.\n\n#### throttleTypeOptions\nType: `Boolean\\Object`\n\nDefault value: null\n\n```js\n$('#container').scrollStory({\n    throttleTypeOptions: null\n});\n```\nOptions to pass to Underscore's throttle or debounce for scroll. Type/functionality dependent on 'throttleType'\n\n#### autoUpdateOffsets\nType: `Boolean`\n\nDefault value: true\n\n```js\n$('#container').scrollStory({\n    autoUpdateOffsets: true\n});\n```\nUpdate offsets after likely repaints, like window resizes and filters. If updates aren't offset, the triggering of scroll events may be inaccurate.\n\n#### enabled\nType: `Boolean`\n\nDefault value: true\n\n```js\n$('#container').scrollStory({\n    enabled: true\n});\n```\nWhether or not the scroll checking is enabled.\n\n#### debug\nType: `Boolean`\n\nDefault value: false\n\n```js\n$('#container').scrollStory({\n    debug: true\n});\n```\nWhether or not the scroll trigger point should be visible on the page.\n\n\n### Events and Callbacks\n\nMost of ScrollStory's functionality is available via callbacks and events. \n\n```js\n\n// via callbacks on instantiation\n$('#container').scrollStory({\n  itemfocus: function(ev, item) {\n    // do something\n  }\n})\n\n// or via events on the container\n$('#container').on('itemfocus', function(ev, item){\n  // do something\n});\n\n```\n\n#### setup\nFired early in instantiation, before any items are added or offsets calculated. Usefull for manipulating the page before ScrollStory does\nanything.\n\n```js\n$('#container').scrollStory({\n  setup: function() {\n    // do something\n  }\n})\n```\n\n\n#### itemfocus\nFired when an item gains 'focus', which can happen from a scroll-based activation (most commonly), or externally via this.index().\n\n```js\n$('#container').scrollStory({\n  itemfocus: function(ev, item) {\n    // do something\n  }\n})\n```\n\n#### itemblur\nFired when an item loses 'focus'.\n\n```js\n$('#container').scrollStory({\n  itemblur: function(ev, item) {\n    // do something\n  }\n})\n```\n\n#### itemfilter\nFired when an item is filtered, which means it is no longer considered when ScrollStory determines which item is currently active. By default, there is no visual change on filter, but you can achive visual changes through this event and css rules.\n\n```js\n$('#container').scrollStory({\n  itemfilter: function(ev, item) {\n    // do something\n  }\n})\n```\n\n#### itemunfilter\nFired when an item is unfiltered.\n\n```js\n$('#container').scrollStory({\n  itemunfilter: function(ev, item) {\n    // do something\n  }\n})\n```\n\n#### itementerviewport\nFired when an item enters the visible portion of the screen. This is useful for triggering things like lazy loads.\n\n```js\n$('#container').scrollStory({\n  itementerviewport: function(ev, item) {\n    // do something\n  }\n})\n```\n\n#### itemexitviewport\nFired when an item leaves the visible portion of the screen.\n\n```js\n$('#container').scrollStory({\n  itemexitviewport: function(ev, item) {\n    // do something\n  }\n})\n```\n\n#### itembuild\nFired when the widget is made aware of an individual item during instantiation. This is a good time to add additional properties to the object. If you're passing in data to build the DOM via the 'content' property, you should append HTML to the item here, as the item hasn't yet been added to the page and the render will be faster.\n\n```js\n$('#container').scrollStory({\n  itembuild: function(ev, item) {\n    item.el.html('\u003cp\u003eMy new content!\u003c/p\u003e');\n  }\n})\n```\n\n#### categoryfocus\nFired when new active item is in a different category than previously active item.\n\n```js\n$('#container').scrollStory({\n  categoryfocus: function(ev, category) {\n    // do something\n  }\n})\n```\n\n\n#### containeractive\nFired when the instance changes states from having no active item to an active item. Depending on instantiation options, this may or not be on instantiation.\n\n```js\n$('#container').scrollStory({\n  containeractive: function() {\n    // do something\n  }\n})\n```\n\n#### containerinactive\nFired when the instance changes states from having an active item to not having an active item.\n\n```js\n$('#container').scrollStory({\n  containerinactive: function() {\n    // do something   \n  }\n})\n```\n\n#### containerscroll\nThrottled scroll event.\n\n```js\n$('#container').scrollStory({\n  containerscroll: function() {\n    // do something\n  }\n})\n```\n\n#### updateoffsets\nFired after offsets have been updated.\n\n```js\n$('#container').scrollStory({\n  updateoffsets: function() {\n    // do something\n  }\n})\n```\n\n#### triggeroffsetupdate\nFired after a trigger offset as been updated via `.updateTriggerOffset()`\n\n```js\n$('#container').scrollStory({\n  triggeroffsetupdate: function() {\n    // do something\n  }\n})\n```\n\n#### scrolloffsetupdate\nFired after a scroll offset as been updated via `.updateScrollOffset()`\n\n```js\n$('#container').scrollStory({\n  scrolloffsetupdate: function() {\n    // do something\n  }\n})\n```\n\n#### complete\nFired when object's instantiation is complete.\n\n```js\n$('#container').scrollStory({\n  complete: function() {\n    // do something\n  }\n})\n```\n\n\n### API\nScrollStory exposes many methods for interacting with the instance. \n\n```js\n// save instance object\nvar scrollStory = $('#container').scrollStory().data('plugin_scrollStory');\n\n// scroll to fourth item\nscrollStory.index(3); \n\n\n// or access the methods from within the object\n$('#container').scrollStory({\n  complete: function() {\n    this.index(3); // scroll to fourth item\n  }\n})\n\n```\n\n#### isContainerActive()\nWhether or not any of the items are active. If so, the entire widget is considered to be 'active.'\n\n#### updateOffsets()\n\nUpdate the object's awareness of each item's distance to the trigger. This method is called internally after instantiation and automatically on window resize. It should also be called externally anytime DOM changes affect your items' position on the page, like when filtering changes the size of an element.\n\n#### index([index])\nGet or set the current index of the active item. On set, also scroll to that item.\n\n###### Arguments\n\n  * *index:* (optional Number) - The zero-based index you want to activate.\n\n#### next()\nConvenience method to navigate to the item after the active one.\n\n\n#### previous()\nConvenience method to navigate to the item before the active one.\n\n#### each(callback)\nIterate over each item, passing the item to a callback.\n\n###### Arguments\n* *callback:* Function\n\n```js\nthis.each(function(item, index){ \n  item.el.append('\u003ch2\u003e'+item.id+'\u003c/h2\u003e');\n});\n```\n\n\n#### getActiveItem()\nThe currently active item object.\n\n#### setActiveItem(item, [options, callback])\nGiven an item object, make it active, including updating its scroll position. \n\n###### Arguments\n\n  * *item:* Object - The item object to activate\n  * *options:* (optional Object) - _scrollToItem options object. TK details.\n  * *callback:* (optional Function) - Post-scroll callback\n\n#### getItems()\nReturn an array of all item objects.\n\n#### getItemsInViewport()\nReturn an array of all item objects currently visible on the screen.\n\n#### getItemsByCategory(slug)\nReturn an array of all item objects in the given category.\n\n###### Arguments\n* *slug:* String - The category slug\n\n#### getFilteredItems()\nReturn an array of all item objects whose filtered state has been set to true.\n\n#### getUnfilteredItems()\nReturn an array of all item objects whose filtered state has been not been set to true.\n\n\n#### getItemById(id)\nGiven an \u003ccode\u003eitem.id\u003c/code\u003e, return its data.\n\n###### Arguments\n* *id:* String - The item.id for the object you want to retrieve.\n\n#### getItemByIndex(index)\n\u003ccode\u003escrollStory.getItemByIndex()\u003c/code\u003e:  Given an item's zero-based index, return its data.\n\n###### Arguments\n* *index:* Number - Zero-based index for the item object you want to retrieve.\n\n\n\n#### getItemsBy(truthTest)\nReturn an array of item objects that pass an aribitrary truth test.\n\n###### Arguments\n* *truthTest:* Function - The function to check all items against\n\n```js\nthis.getItemsBy(function(item){\n  return item.data.slug=='josh_williams';\n});\n```\n\n#### getItemsWhere(properties)\nReturns an array of items where all the properties match an item's properties. Property tests can be any combination of values or truth tests.\n\n###### Arguments\n\n* *properties:* Object \n\n```js\n// Values\nthis.getItemsWhere({index:2});\nthis.getItemsWhere({filtered:false});\nthis.getItemsWhere({category:'cats', width: 300});\n\n// Methods that return a value\nthis.getItemsWhere({width: function(width){ return 216 + 300;}});\n\n// Methods that return a boolean\nthis.getItemsWhere({index: function(index){ return index \u003e 2; } });\n\n// Mix and match:\nthis.getItemsWehre({filtered:false, index: function(index){ return index \u003c 30;} })\n```\n\n#### getPreviousItem()\nMost recently active item.\n\n#### getPreviousItems()\nSorted array of items that were previously active, with most recently active at the front of the array.\n\n#### getFilteredItems()\nReturn an array of all filtered items.\n\n#### getUnfilteredItems()\nReturn an array of all unfiltered items.\n\n\n#### getLength()\nReturn the number of items.\n\n#### getCategorySlugs()\nReturn an array of category slugs.\n\n#### filter(item)\nGiven an item, change its state to filtered.\n\n###### Arguments\n\n* *item:* Object - item object\n\n#### unfilter(item)\nGiven an item, change its state to unfiltered.\n\n###### Arguments\n\n* *item:* Object - item object\n\n#### filterBy(truthTest, [callback])\nFilter items that pass an abritrary truth test.\n\n###### Arguments\n* *truthTest:* Function - The function to check all items against\n* *callback:* (optional Function) - Post-filter callback\n\n```js\nscrollStory.filterBy(function(item){\n    return item.data.slug=='josh_williams';\n});\n```\n#### filterAllItems([callback])\nChange all items' state to filtered.\n\n###### Arguments\n* *callback:* (optional Function) - Post-filter callback\n\n#### unfilterAllItems([callback])\nChange all items' state to unfiltered.\n\n###### Arguments\n* *callback:* (optional Function) - Post-filter callback\n\n#### disable()\nDisable scroll updates. This is useful in the rare case when you want to manipulate the page but not have ScrollStory continue to check positions, fire events, etc. Usually a `disable` is temporary and followed by an `enable`.\n\n#### enable()\nEnable scroll updates.\n\n### Release History\n*1.0.0*\n\n* Bump to 1.0 release.\n\n*0.3.8*\n\n* Fixed [Issue 30](https://github.com/sjwilliams/scrollstory/issues/30): Uneeded `undefined` in module setup.\n* Fixed [Issue 28](https://github.com/sjwilliams/scrollstory/issues/28): Typo in documentation.\n\n*0.3.7*\n\n* Fixed critical typos in documentation.\n\n*0.3.6*\n\n* Added [PR 27](https://github.com/sjwilliams/scrollstory/pull/27) Calculate item's active scroll percent complete.\n\n*0.3.5*\n\n* Added [PR 26](https://github.com/sjwilliams/scrollstory/pull/26) Optionally to bind to event other than native scroll.\n\n*0.3.4*\n\n* Fixed missing 'index' passed to `.each()` callback that was original added in [Issue 7](https://github.com/sjwilliams/scrollstory/issues/7), but got lost in the 0.3 rewrite.\n\n*0.3.3*\n\n* Added [Issue 24](https://github.com/sjwilliams/scrollstory/issues/24) New `setup` event.\n\n*0.3.2*\n\n* Fixed [Issue 20](https://github.com/sjwilliams/scrollstory/issues/20): Item focus should fire after containeractive.\n\n*0.3.1 - Rewrite/Breaking changes*\n\n* A complete rewrite that drops jQuery UI and Underscore dependencies, removes many methods, standardizes naming and more.\n\n*0.2.1*\n\n* Fixed a bug in the name of the scroll event.\n\n*0.2.0*\n\n* Added [Issue 7](https://github.com/sjwilliams/scrollstory/issues/7): `.each` method iterates over each item, passing the item to a callback that is called with two arguments: `item` and `index`.\n\n*0.1.1*\n\n* Fixed [Issue 6](https://github.com/sjwilliams/scrollstory/issues/6): Prevent back arrow key from navigating back if the meta key is down, which browsers use to navigate previous history. \n\n*0.1.0*\n\n* Fixed a bug that allowed widget to go inactive but leave an item active.\n\n*0.0.3*\n\n* Fixed in-viewport bug caused by assumed global jQuery variable.\n* Trigger resize event\n* Debug mode to visually show trigger point\n\n*0.0.2*\n\n* Bower release\n\n*0.0.1*\n\n* Initial release\n\n###License\nScrollStory is licensed under the [MIT license](http://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsjwilliams%2Fscrollstory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsjwilliams%2Fscrollstory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsjwilliams%2Fscrollstory/lists"}