{"id":15673774,"url":"https://github.com/jaydenseric/hurdler","last_synced_at":"2025-05-08T03:11:18.814Z","repository":{"id":57269663,"uuid":"41329063","full_name":"jaydenseric/Hurdler","owner":"jaydenseric","description":"Enables hash links to web page content hidden beneath layers of interaction.","archived":false,"fork":false,"pushed_at":"2016-11-20T08:16:20.000Z","size":53,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-26T11:37:40.236Z","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":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jaydenseric.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-08-24T21:59:25.000Z","updated_at":"2025-02-22T06:52:30.000Z","dependencies_parsed_at":"2022-09-02T12:31:11.005Z","dependency_job_id":null,"html_url":"https://github.com/jaydenseric/Hurdler","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/jaydenseric%2FHurdler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaydenseric%2FHurdler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaydenseric%2FHurdler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaydenseric%2FHurdler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jaydenseric","download_url":"https://codeload.github.com/jaydenseric/Hurdler/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252989952,"owners_count":21836667,"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-10-03T15:42:00.893Z","updated_at":"2025-05-08T03:11:18.798Z","avatar_url":"https://github.com/jaydenseric.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ![Hurdler](https://cdn.rawgit.com/jaydenseric/Hurdler/v4.0.1/hurdler-logo.svg)\n\n![NPM version](https://img.shields.io/npm/v/hurdler.svg?style=flat-square) ![Github issues](https://img.shields.io/github/issues/jaydenseric/Hurdler.svg?style=flat-square) ![Github stars](https://img.shields.io/github/stars/jaydenseric/Hurdler.svg?style=flat-square)\n\nHurdler makes nested UI interactions simple to manage via URL hash.\n\n- ES6 source with efficient transpilation in mind.\n- Less than 1 KB compressed.\n- IE 11 and modern browser support.\n- [MIT license](https://en.wikipedia.org/wiki/MIT_License).\n\n## How it works\n\n1. A sprint is triggered manually or automatically when the URL hash changes with a valid target.\n2. Hurdler sprints up the DOM from the target finding ancestor elements that match hurdles.\n3. Jump callbacks run in top-down DOM order. Often components such as overlays need to be activated before descendants.\n\nLingo  | Meaning\n:----- | :--------------------------------------------------------------------\nTarget | A DOM element targeted via ID in the URL hash; the sprint start line.\nSprint | A sprint up the DOM, looking for hurdles from the target.\nHurdle | A test and stuff to do when a DOM element passes.\nJump   | A hurdle that was found in a sprint.\n\n## Benefits\n\nWhen components such as modals and slideshows are navigated via URL hash:\n\n- Controls are simple hash links; semantic with no click events to manage.\n- Native browser back and forward controls navigate the UI.\n- Component controls such as slideshow next buttons can be right-clicked and opened in a new tab, etc.\n- Intuitively copy the URL to bookmark or share any part of the page.\n\nWith Hurdler:\n\n- Even deeply nested pieces of content can be accessed by a short, single segment URL hash (e.g. `#/pricing`). Aside from looking nicer and being easier to tweet than multi-segment approaches (e.g. `#/section/overview/slide/pricing`), changing structure, components or content is less likely to break existing links.\n- Components define their own hurdles; no centralized routes to setup.\n- Dynamically inserting or moving components around is no problem; every sprint is a fresh search for hurdles to jump.\n\n## Setup\n\nInstall Hurdler in your project as an NPM dependency:\n\n```sh\nnpm install hurdler --save\n```\n\nImport it at the beginning of your app:\n\n```javascript\nimport Hurdler from 'hurdler'\n```\n\nInitialize Hurdler:\n\n```javascript\nconst hurdler = new Hurdler()\n```\n\nSetup hurdles:\n\n```javascript\nhurdler.addHurdle({\n  test: element =\u003e {\n    return element.tagName === 'SECTION'\n  },\n  onJump: element =\u003e {\n    console.log('Jumped a section', element)\n  }\n})\n```\n\nRun a first sprint, after DOM ready:\n\n```javascript\nhurdler.sprint()\n```\n\n## API\n\n### Hurdler\n\nCreates a new Hurdler session. There should only be one instance per window.\n\n**Parameters**\n\n- `$0` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** (optional, default `{}`)\n\n  - `$0.hashPrefix` **[[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** String between URL hash symbol and target element ID to denote Hurdler links. Prevents auto scroll. (optional, default `'/'`)\n  - `$0.onSprintBefore` **[[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)]** Runs before each sprint.\n  - `$0.onSprintAfter` **[[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)]** Runs after each sprint.\n  - `$0.hurdles` **[[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)\u003c[Hurdle](#hurdle)\u003e]** List of hurdles. (optional, default `[]`)\n\n**Examples**\n\n```javascript\nconst hurdler = new Hurdler({\n  hashPrefix: '!/'\n})\n```\n\n#### target\n\nThe current URL hash target element, or null if nonexistent.\n\n**Examples**\n\n```javascript\nconsole.log(hurdler.target)\n```\n\n#### addHurdle\n\nAdds a hurdle.\n\n**Parameters**\n\n- `options` **[Hurdle](#hurdle)** A hurdle.\n\n**Examples**\n\n```javascript\nhurdler.addHurdle({\n  test: element =\u003e {\n    return element.tagName === 'SECTION'\n  },\n  onJump: element =\u003e {\n    console.log('Jumped a section', element)\n  }\n})\n```\n\n#### validateHash\n\nChecks a provided URL hash matches the configured format.\n\n**Parameters**\n\n- `hash` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** A URL hash to validate.\n\n**Examples**\n\n```javascript\nhurdler.validateHash(anExampleLinkElement.hash)\n```\n\nReturns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** URL hash validity.\n\n#### setTarget\n\nSets the URL hash target element, triggering a sprint.\n\n**Parameters**\n\n- `element` **[HTMLElement](https://developer.mozilla.org/en-US/docs/Web/HTML/Element)** Element with an ID to target.\n\n**Examples**\n\n```javascript\nhurdler.setTarget(anExampleElement)\n```\n\n#### clearTarget\n\nClears the window URL hash if a given element is targeted, or if the URL hash matches the configured Hurdler format.\n\n**Parameters**\n\n- `element` **[[HTMLElement](https://developer.mozilla.org/en-US/docs/Web/HTML/Element)]** Element with an ID that you do not want targeted.\n\n**Examples**\n\n```javascript\nhurdler.clearTarget(anExampleElement)\n```\n\n#### sprint\n\nJumps hurdles and runs callbacks for the current URL hash. Use after all hurdles have been added and the document is ready. Triggered automatically by URL hash changes.\n\n**Examples**\n\n```javascript\nhurdler.sprint()\n```\n\n### Hurdle\n\nAn object holding a test and callbacks for when a DOM element passes.\n\n**Properties**\n\n- `test` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** Accepts an element and returns a boolean if it matches the hurdle.\n- `onJump` **[[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)]** Runs when the hurdle is jumped.\n\n**Examples**\n\n```javascript\n{\n  test: element =\u003e {\n    return element.tagName === 'SECTION'\n  },\n  onJump: element =\u003e {\n    console.log('Jumped a section', element)\n  }\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaydenseric%2Fhurdler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjaydenseric%2Fhurdler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaydenseric%2Fhurdler/lists"}