hashjump

hashjump

A tiny, dependency-free JavaScript module for handling anchor links and scrolling elements into view.

Features

• Tiny (Around ~8kb minified)
• Zero dependencies
• Supports horizontal as well as vertical scrolling
• Supports easing functions for scrolling animations (even custom ones so things like d3-ease are supported!)
• Supports custom functions for when anchor links are clicked or the page was visited with an anchor link
• Scroll the window to bring your element to the center of the viewport (or any other position in the viewport)

Demo

Visit https://hashjump.js.org

Installation

Manual Download

Download the latest version of hashjump and then place the following HTML in your page's head element:

<script type="text/javascript" src="dist/hashjump.min.js"></script>

CDN (Courtesy of jsDelivr)

Place the following HTML in your page's head element (check to make sure the version in the URLs are the version you want):

<script type="text/javascript" src="https://cdn.jsdelivr.net/gh/kodie/hashjump@0.0.1/dist/hashjump.min.js"></script>

NPM

npm install hashjump --save

// ES6
import hashjump from 'hashjump'
// CommonJS
const hashjump = require('hashjump')

GPM

gpm install kodie/hashjump --save

Bower

bower install kodie/hashjump --save

Usage

hashjump Function

hashjump([targetHashes], [opts])

hashjump([opts])

Initializes hashjump for the defined targetHashes anchor links (or all anchor links if omitted). Sets page load and link click event handlers and saves opts.

Note: If running this function multiple times, you should always call any instances with targetHashes set before calling an instance without (global instance).

Parameters

• targetHashes (Optional) - Accepts a string or an array of strings defining anchor links (minus the #) that should be targeted for this instance.

• opts (Optional) - Accepts an object of options you can define to change the behavior of hashjump. (See Options Section)

Examples

document.addEventListener('DOMContentLoaded', function () {
  hashjump('section-2', {
    hideUrlHash: true,
    focusElement: true
  })

  hashjump('section-4', {
    easingFunction: function (t) { return d3.easeElasticInOut(t) },
    scrollDuration: 2000,
    scrollOffset: 'inner-50%'
  })

  hashjump({
    actionAfter: function (info) { console.log(info) }
  })
})

hashjump.to Function

hashjump.to([target], [opts])

hashjump.to([opts])

Scrolls to the specified target. Retains any opts that may have been previously set by the hashjump() init function but can be overwritten with the opts parameter.

Paramters

• target - Accepts a string of the anchor link or element ID (minus the #), an instance of HTMLElement, or null to use the document body as the element to scroll to.

• opts (Optional) - Accepts an object of options you can define to change the behavior of hashjump. (See Options Section)

Options

action

A function that will replace the scroll event and gets passed an object as the only parameter with some useful information about the instance (See Action Info Section). Useful for performing an action other than scrolling to an element when an anchor link is clicked or visited.

actionAfter

A function that will be ran after the scroll event and gets passed an object as the only parameter with some useful information about the instance (See Action Info Section).

actionBefore

A function that will be ran before the scroll event and gets passed an object as the only parameter with some useful information about the instance (See Action Info Section). If this function returns false, the scroll event will not occur.

focusElement

Decides if the element should be focused after the scroll event or not. Accepts a selector string that is passed to element.matches, a custom function that is passed the element as it's only parameter and should return boolean, or a boolean.

hashjumpLinks

Decides if anchor links on the page should have hashjumpLinkEvents attached to them that runs the hashjump.to() function. Accepts a boolean.

Note: This option is only used by the hashjump() init function.

hashjumpLinkEvents

An array of strings defining event listener types that should be attached to anchor links if the hashjumpLinks option is set to true.

Note: This option is only used by the hashjump() init function.

hashjumpOnLoad

Decides if a load event listener should be attached to the window that runs the hashjump.to() function when the page was visited with an anchor link. Accepts a boolean.

Note: This option is only used by the hashjump() init function.

hideUrlHash

Decides if the anchor id should be displayed in the address bar. Accepts a boolean.

Note: This option is only used by the hashjump() init function.

ignoreEmptyHashes

Decides if an anchor link with an empty hash should be ignored.

Note: This option is only used by the hashjump() init function.

scrollOffset

The amount of pixels offset to the viewport and element position that the window should scroll to. For example, an offset of 5 would scroll the window to where the top of the element ends up at 5 pixels from the top of the viewport.

A string ending with a % can be passed to use a percentage based on the viewport rather than a specific pixel value. For example an offset of "25%" would scroll the window to where the top of the element ends up 25% from the top of the viewport.

Lastly, a string begining with inner- and ending with a % can be passed to use a percentage based on the viewport and the element size. For example, an offset of "inner-50%" would scroll the window to where the center of the element ends up in the center of the viewport.

scrollOffsetX

Does the same as the scrollOffset option but only for the horizontal axis. (Falls back to scrollOffset if left blank)

scrollOffsetY

Does the same as the scrollOffset option but only for the vertical axis. (Falls back to scrollOffset if left blank)

scrollDuration

The number of milliseconds the scroll event should take.

scrollDurationOnLoad

The number of milliseconds the scroll event should take on page load. (Falls back to scrollDuration if left blank)

scrollDurationOnClick

The number of milliseconds the scroll event should take on anchor link click. (Falls back to scrollDuration if left blank)

easingFunction

The easing function used to animate the scroll event. Accepts a custom function that is passed the specified normalized time (t) as it's only parameter. This is useful if you wish to use an easing function from something like d3-ease.

This option also accepts a string to set the easing function to one of the easing functions that hashjump comes with built-in. These include: linear, easeInQuad, easeOutQuad, easeInOutQuad, easeInCubic, easeOutCubic, easeInOutCubic, easeInQuart, easeOutQuart, easeInOutQuart, easeInQuint, easeOutQuint, and easeInOutQuint.

Default Options

{
  action: null,
  actionAfter: null,
  actionBefore: null,
  focusElement: 'input, select, button, textarea',
  hashjumpLinks: true,
  hashjumpLinkEvents: ['click', 'keypress'],
  hashjumpOnLoad: true,
  hideUrlHash: false,
  ignoreEmptyHashes: true,
  scrollOffset: '25%',
  scrollOffsetX: null,
  scrollOffsetY: null,
  scrollDuration: 200,
  scrollDurationOnLoad: null,
  scrollDurationOnClick: null,
  easingFunction: 'linear'
}

Action Info

This is an example of the object that is passed to functions defined in the action, actionAfter, and actionBefore options.

{
  duration: 200
  easeFunc: ƒ easeFunc(t)
  element: div#table-of-contents
  elementHeight: 270
  elementPosX: 127
  elementPosY: 471
  elementWidth: 832
  focusElement: ƒ focusElement()
  maxScrollX: 0
  maxScrollY: 2000
  opts: {...}
  pageHeight: 2895
  pageWidth: 1086
  requestAnimationFrame: ƒ requestAnimationFrame()
  scrollOffsetX: 271.5
  scrollOffsetY: 223.75
  scrollPointX: 0
  scrollPointY: 247.25
  scrollStartX: 0
  scrollStartY: 806.5
  step: ƒ step()
  target: "table-of-contents"
  time: 1678033694771
  viewHeight: 895
  viewWidth: 1086
}

Related

• colorfield - A tiny, dependency-free, color input field helper that utilizes the native color picker.

• filebokz - A tiny, dependency-free, highly customizable and configurable, easy to use file input with some pretty sweet features.

• kloner - A tiny, dependency-free JavaScript module for cloning/repeating elements.

• minitaur - The ultimate, dependency-free, easy to use, JavaScript plugin for creating and managing modals.

• vanishing-fields - A dependency-free, easy to use, JavaScript plugin for hiding and showing fields.

License

MIT. See the license file for more info.