Hurdler makes nested UI interactions simple to manage via URL hash.
- ES6 source with efficient transpilation in mind.
- Less than 1 KB compressed.
- IE 11 and modern browser support.
- MIT license.
How it works
- A sprint is triggered manually or automatically when the URL hash changes with a valid target.
- Hurdler sprints up the DOM from the target finding ancestor elements that match hurdles.
- Jump callbacks run in top-down DOM order. Often components such as overlays need to be activated before descendants.
Lingo | Meaning |
---|---|
Target | A DOM element targeted via ID in the URL hash; the sprint start line. |
Sprint | A sprint up the DOM, looking for hurdles from the target. |
Hurdle | A test and stuff to do when a DOM element passes. |
Jump | A hurdle that was found in a sprint. |
Benefits
When components such as modals and slideshows are navigated via URL hash:
- Controls are simple hash links; semantic with no click events to manage.
- Native browser back and forward controls navigate the UI.
- Component controls such as slideshow next buttons can be right-clicked and opened in a new tab, etc.
- Intuitively copy the URL to bookmark or share any part of the page.
With Hurdler:
- 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. - Components define their own hurdles; no centralized routes to setup.
- Dynamically inserting or moving components around is no problem; every sprint is a fresh search for hurdles to jump.
Setup
Install Hurdler in your project as an NPM dependency:
npm install hurdler --save
Import it at the beginning of your app:
Initialize Hurdler:
const hurdler =
Setup hurdles:
hurdler
Run a first sprint, after DOM ready:
hurdler
API
Hurdler
Creates a new Hurdler session. There should only be one instance per window.
Parameters
-
$0
Object (optional, default{}
)$0.hashPrefix
[String] String between URL hash symbol and target element ID to denote Hurdler links. Prevents auto scroll. (optional, default'/'
)$0.onSprintBefore
[function] Runs before each sprint.$0.onSprintAfter
[function] Runs after each sprint.$0.hurdles
[Array<Hurdle>] List of hurdles. (optional, default[]
)
Examples
const hurdler = hashPrefix: '!/'
target
The current URL hash target element, or null if nonexistent.
Examples
console
addHurdle
Adds a hurdle.
Parameters
options
Hurdle A hurdle.
Examples
hurdler
validateHash
Checks a provided URL hash matches the configured format.
Parameters
hash
string A URL hash to validate.
Examples
hurdler
Returns boolean URL hash validity.
setTarget
Sets the URL hash target element, triggering a sprint.
Parameters
element
HTMLElement Element with an ID to target.
Examples
hurdler
clearTarget
Clears the window URL hash if a given element is targeted, or if the URL hash matches the configured Hurdler format.
Parameters
element
[HTMLElement] Element with an ID that you do not want targeted.
Examples
hurdler
sprint
Jumps 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.
Examples
hurdler
Hurdle
An object holding a test and callbacks for when a DOM element passes.
Properties
test
function Accepts an element and returns a boolean if it matches the hurdle.onJump
[function] Runs when the hurdle is jumped.
Examples
{ return elementtagName === 'SECTION' } { console }