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

Get the latest updates on this jQuery plugin via RSS

Zebra_Pin is a lightweight (around 2KB minified) and adaptive (things work as expected when you manually resize the browser window) jQuery plugin for pinning elements to the page or to a container element, so that the element stays visible even if the user scrolls the page. This type of elements are also refered to as “fixed position elements” or “sticky elements”.

You can use it in your projects 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, pinned elements that move only inside their parent element.

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 calling the plugin make sure that this change will not affect your page’s layout.

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

Features

  • elements can be pinned inside a container element, not just to the page
  • custom events are fired when pinning/unpinning elements offering even more control
  • it is small – it weights around 2KB minified offering the best ratio of features per used bytes
  • it’s cross-browser – works in every major browser and IE7+
  • it is available as a Bower package and as an npm package

Top

Requirements

Zebra_Pin requires jQuery 1.4.2+

Top

How to use

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

bower install zebra_pin

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

npm install zebra_pin

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-1.12.0.min.js"></script>
<script>window.jQuery || document.write('<script src="path/to/jquery-1.12.0.js"><\/script>')</script>

Load the Zebra_Pin plugin

<script type="text/javascript" src="path/to/zebra_pin.js"></script>

Usage

// 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($('#myelement'));

    // 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($('#myelement'), {
        top_spacing: 10
    });

    // if you want the element to be restrained 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($('#myelement'), {
        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($('#myelement'), {
        hard: true
    });
 
});
See the live example.

Top

Properties

class_name string

Class to add to the element when it is “sticky” 

contain boolean

Specifies whether the pinned element should be restrained to its parent element’s boundaries or not. 

Default is FALSE

hard boolean

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. 

Default is FALSE

top_spacing integer

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. 

Default is FALSE

bottom_spacing integer

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 

Default is FALSE

z_index integer

the value of zIndex CSS property to be set for pinned elements

Default is 9999

Events

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($('#my_pinned_element'), {
  // element can move only inside
  // the parent element
  'contain':  true
});

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

Top 

Download

version 1.0.9
If you find this library to be useful to you, you can support the author by donating a small amount via PayPal:

Alternatively, you could show your support by starring this library on GitHub
Star

Zebra_Pin is distributed under the LGPL.

In plain English, this means that you have the right to view and to modify the source code of this software, but if you modify and distribute it, you are required to license your copy under a LGPL-compatible license, and to make the entire source code of your derivation available to anybody you distribute the software to.

You also have the right to use this software together with software that has different licensing terms (including, but not limited to, commercial and closed-source software), and distribute the combined software, as long as state that your software contains portions licensed under the LGPL license, and provide information about where the LGPL licensed software can be downloaded.

If you distribute copies of this software you may not change the copyright or license of this software.


You may also like:

Top

Changelog

Click on a version to expand/collapse information.

version 1.0.9 (January 26, 2016)
version 1.0.5 (January 20, 2016)
  • better integration with Bower
version 1.0.0 (December 07, 2013)
  • initial release

Top

8 responses to “Zebra_Pin, a lightweight jQuery plugin for pinning any element to the page or to a container element”

Follow the comments via RSS
  • WaKeMaTTa, 2013-12-11, 14:05

    Hooo, i liked πŸ˜€

    Reply
  • Lynn, 2013-12-12, 23:57

    Nice addition to your already AWESOME set of tools…:)

    Reply
  • felix, 2014-01-22, 01:57

    Thanks!! Nice Plugin!

    Reply
  • muhanad, 2014-07-02, 09:32

    i used the plugin as you described, but it say Zebra_Pin is undefined !!
    any idea. (all needed scripts are included)

    Reply
    • Stefan Gabos, 2014-07-02, 09:43

      my examples were wrong…it’s

      new $.Zebra_Pin()

      instead of

      new Zebra_Pin()
  • Eric, 2014-10-03, 22:43

    really nice plugin, although I’m not able to make the sticky element contained in its parent/container.. using only contained: true doesn’t work.

    Please advise.

    Eric

    Reply
    • Arep, 2015-05-04, 23:58

      Same problem here πŸ™
      jQuery 1.11.2

  • Sebastiaan, 2014-10-06, 15:15

    Hi Stefan,

    The pinning works great, but I am also trying to pin elements that have a dropdown in it. The dropdown alas gets moved to the top left of its containing element. Is this easily fixed within the plugin, or should I try and find another plugin? Will send screenshot if that more easily explains my situation.

    Thanx up front!

    Reply

Leave a Reply

Your email address will not be published
You can use <strong>, <em>, <a>, <img>, <code>
Characters are not case-sensitive