zebra_pin

Zebra_Pin

A lightweight jQuery plugin for pinning any element to the page or to a container element

Zebra_Pin is a lightweight (2KB minified, ~800 bytes gzipped) and adaptive (things work as expected when the browser window is resized) jQuery plugin for pinning elements to the page or to a container element, so that the pinned elements stay visible even if the user scrolls the page. This type of elements are also referred to as fixed position elements or sticky elements.

Use it to create sticky sidebars, sticky navigation, sticky headers and footers, or anything else you feel the need to make it stick to the page while the user scrolls.

You can have hard pinned elements - elements are pinned to their initial position and stay there, elements that become pinned only when the user scrolls to them and pinned elements whose movement is restricted to their container element's size.

When elements become pinned a CSS class will be added to them, as specified by the plugin's class_name property.

Also, custom events are fired when elements are pinned/unpinned giving you even more power for customizing the result.

Note that this plugin will alter the target element(s) "position" property to absolute and/or fixed, depending on the situation, so, before enabling the plugin, make sure that this will not affect your page's layout.

Works in all major browsers (Firefox, Opera, Safari, Chrome, Internet Explorer 7+)

Support the development of this project

Features

• elements can be pinned inside a container element, not just to the page
• custom events are fired when pinning/unpinning elements for more control
• it is really small – it weights 2KB minified (~800 bytes gzipped) offering a very good ratio of features per used bytes
• it's cross-browser – works in every major browser and IE7+

Requirements

Zebra_Pin has no dependencies other than jQuery 1.7+

Installation

Zebra_Pin is available as a npm package. To install it use:

npm install zebra_pin

Zebra_Pin is also available as a Bower package. To install it use:

bower install zebra_pin

How to use

First, load the latest version of jQuery from a CDN and provide a fallback to a local source, like:

<script src="https://code.jquery.com/jquery-3.2.1.min.js"></script>
<script>window.jQuery || document.write('<script src="path/to/jquery-3.2.1.js"><\/script>')</script>

Load the Zebra_Pin jQuery plugin:

<script src="path/to/zebra_pin.min.js"></script>

Alternatively, you can load Zebra_Pin from JSDelivr CDN like this:

// for the most recent version
<script src="https://cdn.jsdelivr.net/gh/stefangabos/Zebra_Pin/dist/zebra_pin.min.js"></script>

// for a specific version
<script src="https://cdn.jsdelivr.net/gh/stefangabos/Zebra_Pin@1.1.1/dist/zebra_pin.min.js"></script>

// replacing "min" with "src" will serve you the non-compressed version

Now, within the DOM-ready event, pin elements to page or to a container:

$(document).ready(function() {

    // easiest way to get started: when the user scrolls to the element
    // the element will become pinned (sticky) and will scroll with the page
    new $.Zebra_Pin($('#element'));

    // in the example above, the element will be at the very top edge of the
    // screen. if you want to add some top margin simply set the "top_spacing"
    // property
    new $.Zebra_Pin($('#element'), {
        top_spacing: 10
    });

    // if you want the element to be restricted to the height of the container
    // element, simply set the value of the "container" property to TRUE
    // (make sure the container element has its "position" set to "relative" or
    // "absolute")
    new $.Zebra_Pin($('#element'), {
        contained: true
    });

    // or, you may want to pin an element *exactly* to the position where it's at
    // and make it stay there no matter what (we'll call this a "hard" pin)
    new $.Zebra_Pin($('#element'), {
        hard: true
    });

});

Configuration options

Properties

Property	Type	Default	Description
class_name	string	Zebra_Pin	Class to add to the element when it is "sticky"
contain	boolean	FALSE	Specifies whether the pinned element should be restricted to its parent element's boundaries or not. The container element must have the position CSS property set to something other than static
hard	boolean	FALSE	Specifies whether the element should be "hard" pinned (the element is pinned to its position from the beginning), or become pinned only when it is about to be hidden.
top_spacing	integer	0	Margin, in pixels, from the container element's (or the browser window's) top. This only works if the "hard" property is set to FALSE.
bottom_spacing	integer	0	Margin, in pixels, from the container element's bottom This only works if the "hard" property is set to FALSE and it is used only if the "contain" property is TRUE
z_index	integer	9999	The value of zIndex CSS property to be set for pinned elements

Events

Event	Description
onPin	Callback function to be executed when an element is pinned The callback function receives 3 arguments: the vertical position, relative to the document, where the event occurred a reference to the pinned element the index of the element - if the plugin was attached to multiple elements (0 based)
onUnpin	Callback function to be executed when an element is unpinned The callback function receives 3 arguments: the vertical position, relative to the document, where the event occurred a reference to the unpinned element the index of the element - if the plugin was attached to multiple elements (0 based)

Methods

update()

Updates the pinned elements' positions in accordance with the scrolled amount and with the pinned elements' container elements (if any).

Useful if a pinned element's parent changes height.

// initialize the plugin
var zp = new $.Zebra_Pin($('#element'), {

    // element can move only inside
    // the parent element
    contain:  true

});

// if the parent element's height changes
// update also the boundaries
zp.update();

Demo

See the demos

Changelog

version 1.1.2 (May 30, 2017)

• fixed a bug with contained pins where things were not working as expected if the container element would have a position other than "static"
• new folder structure
• performance improvements and source code tweaks
• the home of the library is now exclusively on GitHub
• files required in the build process are not included anymore when installing via npm nor when downloading from GitHub