pinnd › Documentation

pinnd.js is a javascript plugin pinning content relative to the viewport when scrolling. The plugin focuses heavily on performance while still offering a lot of very useful functionality.

Dependencies

pinnd.js requires jQuery 1.7+ to run.

Usage

Once you have included the pinnd.js file in your page, you can initialize the plugin by calling the pinnd() function. The pinnd() function takes two parameters:

obj (required):
jQuery object(s) that you want the plugin to manipulate
options (optional)
Options object. See below for available options

While not a traditional jQuery plugin, pinnd does rely on jQuery, so make sure you're calling the pinnd() function within your $(document).ready() block.

1
2
3
4
5
6
7
8
9
// Sample JS
$(document).ready(function() {
    // Select object(s)
    var obj = $('.my-objects');
    var opts = {
        offset: 20
    }
	pinnd(obj, opts);
});

Return value

Calling pinnd() returns an object which can be used to access the public methods (see below).

The options object

The options object can set any of the following properties:

Property	Type	Default	Description
context	string	body	jQuery compatible selector string for the context object that you want the pinned element to be restrained to. By default, pinned objects are constrained to the body element.
autoenable	boolean	true	Set to `false` to prevent the plugin from enabling as part of the initialization process. If you set this to false, you will need to manually enable the pinning behavior via the `on()` public method
offset_top	int	0	Pixel offset to pin the element from the top of the window.
offset_bottom	int	0	Pixel offset to pin the element from the top of the bottom of the context element.
onpintop	function	null	Callback function triggered when the element is pinned to the top of the viewport/context element. Passes a jQuery reference to the pinned object as its single argument.
onpinbottom	function	null	Callback function triggered when the element is pinned to the bottom of the viewport/context element. Passes a jQuery reference to the pinned object as its single argument.
onunpin	function	null	Callback function triggered when the element is unpinned from the viewport/context element. Passes a jQuery reference to the pinned object as its single argument.

CSS Classes

pinnd adds several CSS classes to pinnable elements depending on their state. This makes the elements easy to target elsewhere in your scripts or in CSS. Classes are added when the elements enter the associated state and are automatically removed when they exit the associated state.

CSS Class	Applied when
.pinnd	Applied when an element enters a pinned state (either to the top or the bottom of the context element)
.pinnd-top	Applied when an element enters a pinned state at the top of the context element
.pinnd-bottom	Applied when an element enters a pinned state at the bottom of the context element

Public methods

pinnd exposes public methods which are returned as an object to the pinnd() function call. To utilize the public methods, simply capture the return in a variable and call the public methods as methods of that variable.

1
2
3
4
5
// Example of calling a public method
$(document).ready(function() {
    var myPinnd = pinnd($('.mypinnd'));
    myPinnd.off();
});

.off()

The off() method disables pinning for the associated elements. Note that if elements are currently in a pinned state, calling off() will return them to their original positions.

.on()

The on() method enables pinning for the associated elements. Note that calling on() will automatically pin any necessary elements.

Both the on() and off() methods only affect their associated elements. This means that if you have created multiple sets of pinnable elements (to give them different options for example), calling one of the public methods will only affect the set of elements associated with the public method you are calling.