Page scroll to id

Last updated on Feb 26, 2021 Originally published on January 3, 2014 by malihu, under Plugins, WordPress.

Page scroll to id is an easy-to-use jQuery plugin that enables animated page scrolling to specific id within the document. The plugin replaces the default browser behaviour of “jumping” to page sections when links with href value containing hash (#) are clicked, by smoothly animating the page to those sections. You can use it for simple back-to-top links or complex, single-page website navigation and features include: adjustable animation speed, advanced animation easings, vertical and/or horizontal scrolling, ready-to-use classes for links highlighting etc.

view demo horizontal layout
auto layout
dynamic content example
example with jquery.address
example with jquery-hashchange

Release archive
Page scroll to id for WordPress
Project on GitHub

Current version 1.6.8 (Changelog)

How to use it

The plugin works simply by connecting links in the form of <a href="#id">link</a>, to sections within the document, in the form of <div id="id">target</div>. Clicking the links will smoothly animate the page to the connected sections.

Get started by Downloading the archive which contains all plugin files and examples. Extract and upload jquery.malihu.PageScroll2id.min.js to your web server.

Include jQuery library (if your project doesn’t use it already) and jquery.malihu.PageScroll2id.min.js in your document’s head tag or at the very bottom of your html, just before the closing body tag (recommended for better performance)

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js"></script>
<script src="jquery.malihu.PageScroll2id.min.js"></script>

After files inclusion, call mPageScroll2id function on the matching set of elements (selectors) you want the plugin to handle

<script>
    (function($){
        $(window).on("load",function(){
            $("a[rel='m_PageScroll2id']").mPageScroll2id();
        });
    })(jQuery);
</script>

Using the a[rel='m_PageScroll2id'] selector above, means that the plugin will apply on links with m_PageScroll2id rel attribute value (e.g. <a href="#id" rel="m_PageScroll2id">link</a>). You can change the selector to anything you want (id, class name, js variable etc. – strings that represent ways of choosing elements in the DOM). For multiple selectors, use comma separated values: e.g. a[rel='m_PageScroll2id'], a.class-name, li.menu-item a[href*='#'].

Your links href value should contain # with the id of the section you want to scroll-to and your document should contain sections with such id.

more info

The code is wrapped in (function($){ ... })(jQuery);. This ensures no conflict between jQuery and other libraries using $ shortcut (see Avoiding Conflicts with Other Libraries for more info).

Plugin function is called on window load ($(window).on("load")) so it executes after all page elements are fully loaded, ensuring the script calculates correctly your content’s length.

By default, the plugin scrolls the page vertically. If your page layout is horizontal (demo), set the layout option parameter to horizontal

$("a[rel='m_PageScroll2id']").mPageScroll2id({
    layout:"horizontal"
});

To enable both vertical and horizontal scrolling (demo), set layout to auto

$("a[rel='m_PageScroll2id']").mPageScroll2id({
    layout:"auto"
});

Page scroll to id provides a ready-to-use class for the highlighted links (links whose target element is considered to be within the viewport). The default highlight class is mPS2id-highlight, which you can use in your CSS to style your highlighted links (more info). For example:

a.mPS2id-highlight{ 
    background: #ff0; 
}

This sums up the basics of implementing Page scroll to id in your project. For help and detailed usage guides see Code examples & short tutorials and FAQ.

Configuration

Page scroll to id option parameters
Usage $(selector).mPageScroll2id({ option: value });

scrollSpeed: integer

Sets the scroll animation speed in milliseconds (default: 1300).
Example:

$(selector).mPageScroll2id({ scrollSpeed: 900 });

autoScrollSpeed: boolean

Auto-adjusts animation speed according to target element position and window scroll (default: true).
Example:

$(selector).mPageScroll2id({ autoScrollSpeed: true });

scrollEasing: "string"

Sets the animation easing type when page is idle (easings).
Example:

$(selector).mPageScroll2id({ scrollEasing: "easeInOutQuint" });

scrollingEasing: "string"

Sets the animation easing type while page is animating (easings).
Example:

$(selector).mPageScroll2id({ scrollingEasing: "easeOutQuint" });

pageEndSmoothScroll: boolean

Adjusts automatically the scroll-to position so when scrolling to a target element that sits at the bottom of the document, the animation stops smoothly at bottom of the page, instead of breaking at an earlier point (default: true).
Example:

$(selector).mPageScroll2id({ pageEndSmoothScroll: true });

layout: "string"

Defines the page scrolling axis.
Value can be "vertical", "horizontal" or "auto".
Example:

$(selector).mPageScroll2id({ layout: "vertical" });

offset: integer, "string", object, function: Defines the amount of pixels to offset the scroll-to position.
The value can a be a positive/negative number, an element selector as string, a js/jquery object, a function or an array.
Code examples

highlightSelector: "string": The matching set of elements already handled by the plugin that will be highlighted (by default, all selectors are eligible for highlighting).
Code examples

clickedClass: "string": Sets the class name for the link that’s been clicked (default: mPS2id-clicked)

targetClass: "string": Sets the class name for the (current) target element (default: mPS2id-target).

highlightClass: "string": Sets the class name for the (current) highlighted link (default: mPS2id-highlight).
Code examples

forceSingleHighlight: boolean

Allows only one highlighted element at a time (default: false).
Example:

$(selector).mPageScroll2id({ forceSingleHighlight: true });

keepHighlightUntilNext: boolean

Keeps element highlighted until next so at least one element always stays highlighted (default: false)).
Example:

$(selector).mPageScroll2id({ keepHighlightUntilNext: true });

highlightByNextTarget: boolean

Highlight elements according to their target and next target position (default: false).
Useful when targets have zero dimensions.
Example:

$(selector).mPageScroll2id({ highlightByNextTarget: true });

disablePluginBelow: boolean: Disables plugin below [width,height] screen size: boolean, integer, array ([width,height]).

clickEvents: boolean

Enable/disable click events for all selectors (default: true).
Example:

$(selector).mPageScroll2id({ clickEvents: false });

appendHash: boolean

Append link’s href hash value to browser’s URL/address bar when clicked (default: false).
Example:

$(selector).mPageScroll2id({ appendHash: true });

onStart:function(){}: User defined callback function, triggered when scrolling animation begins.
Code examples

onComplete:function(){}: User defined callback function, triggered when scrolling animation is completed.
Code examples

liveSelector: "string"

The matching set of elements that will be handled by the plugin even if they’re not present in the DOM (e.g. dynamic elements that will be added later on).
Example:

$(selector).mPageScroll2id({ liveSelector: "a.my-future-class" });

excludeSelectors: "string"

The matching set of elements that will be excluded from the plugin (i.e. the plugin will not handle these elements).
Example:

$(selector).mPageScroll2id({ excludeSelectors: "a[href^='#tab-'], a[href^='#tabs-']" });

encodeLinks: boolean

Encode links selector when their href/URL have encoded unicode characters, e.g. on internationalized domain names (default: false).
Example:

$(selector).mPageScroll2id({ encodeLinks: true });

inIframe: boolean

Enable to run the script inside iframe.
Example:

$(selector).mPageScroll2id({ inIframe: true });

Plugin methods

scrollTo

Usage $.mPageScroll2id("scrollTo","#id");

Calling plugin’s scrollTo method will automatically scroll the page to the id specified in the second parameter.

Method option parameters

layout: "string"

Defines the page scrolling axis.
Example:

$.mPageScroll2id("scrollTo","#id",{
    layout:"auto"
});

offset: integer

Defines the amount of pixels to offset the scroll-to position.
Example:

$.mPageScroll2id("scrollTo","#id",{
    offset:100
});

clicked: boolean

The jQuery object to simulate the click event.
Example:

$.mPageScroll2id("scrollTo","#id",{
    clicked:$(this)
});

destroy

Usage $.mPageScroll2id("destroy");

Calling plugin’s destroy method will completely remove Page scroll to id functionality from all links and targets, returning them to their original state. The method removes all plugin-specific classes, data objects and namespaced events.

Plugin dependencies & requirements

jQuery version 1.7.0 or higher

License

This work is released under the MIT License.
You are free to use, study, improve and modify it wherever and however you like.
https://opensource.org/licenses/MIT

Donating helps greatly in developing and updating free software and running this blog 🙂

Pages: 1 2 3 4

Page scroll to id

How to use it

Configuration

Plugin methods

scrollTo

Method option parameters

destroy

Plugin dependencies & requirements

License

Tags

638 Comments

Post a comment

Page scroll to id

How to use it

Configuration

Plugin methods

scrollTo

Method option parameters

destroy

Plugin dependencies & requirements

License

Tags

Posts related to this article

638 Comments

Post a comment