zebra_pin

Zebra Pin  

A lightweight jQuery plugin for pinning elements to the page or to container elements

Zebra_Pin is a lightweight (2.5KB 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 pinned elements remain visible when they are about to be scrolled out of view. 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 when they are about to be scrolled out of view, as well as pinned elements that can move only inside their parent element's boundaries.

Pinned elements are added a user-defined CSS class so you can adjust their looks when pinned. Additionally, custom events are fired when elements become pinned/unpinned giving you even more power for customizing the result.

Works in pretty much any browser - Firefox, Chrome, Safari, Edge, Opera and Internet Explorer 7+

Features

• elements can be pinned inside a container element, not just to the page
• pinned elements are added a user-defined CSS class so you can adjust their looks when pinned
• custom events are fired when elements become pinned/unpinned giving you even more power for customizing the result
• it is really small – it weights 2.5KB 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+

Demo

See the demos

Requirements

Zebra Pin has no dependencies other than jQuery 1.7+

Installation

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

# the "--save" argument adds the plugin as a dependency in packages.json
npm install zebra_pin --save

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

# the "--save" argument adds the plugin as a dependency in bower.json
bower install zebra_pin --save

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.3.1.min.js"></script>
<script>window.jQuery || document.write('<script src="path/to/jquery-3.3.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, not recommended in production -->
<script
    src="https://cdn.jsdelivr.net/npm/zebra_pin@latest/dist/zebra_pin.min.js"></script>

<!-- for a specific version -->
<script
    src="https://cdn.jsdelivr.net/npm/zebra_pin@2.0.0/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)
    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"	CSS class to be added to the element when it becomes pinned
contain	boolean	false	Specifies whether the pinned element should be restricted to its parent element's boundaries or not. The container element must have its position set to something other than the default 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 go out of view.
top_spacing	integer	0	Distance, in pixels, from the browser window's top (or the container element's top, when the element is contained to its parent element's boundaries) from which the element should become pinned. This only works if the hard property is set to false.
bottom_spacing	integer	0	Distance, in pixels, from the containing parent element's bottom which the pinned element must not exceed. This only works if the hard property is set to false and the contain property is set to true
z_index	integer	1000	The value of zIndex CSS property to be set for pinned elements

Events

Event	Description
onPin	Callback function to be executed when an element becomes 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 becomes unpinned (reverts to its original state) 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();

Support the development of this project

Sponsors

Cross browser/device testing is done with

Changelog

version 2.0.0 (July 23, 2018)

• pinned elements are not taken out of DOM when becoming pinned; instead, an invisible clone element is created so that layout doesn't break.
• fixed bug where elements without explicit width would break when becoming pinned
• fixed bug where elements pinned to a container element would incorrectly fire the callback events
• completely rewritten examples
• added version number as a public property - useful to find out the version number even if all you have is the minified source code