« Back to GitHub Repo

## Purpose

Clingify is a jQuery plugin that allows you to easily create “sticky” headers and navigation elements. Once you scroll past the targeted element, the plugin will toggle a CSS class that gives the element a fixed position, pinning it to the top of the page.

## Features

There are many other “sticky” / “clingy” plugins out there, but here are a few reasons to consider Clingify:

- No inline CSS. Everything is controlled via classes, so you don't need to understand Javascript to use this plugin. I have included some sensible default CSS, but you are free to edit it.
- Seriously, though. Inline CSS is a pain in the butt.
- It is possible to have multiple sticky elements on the same page. Simply pass an additional class via the "extraClass" parameter when initializing the plugin. By manipulating z-index and/or top positions, it's possible to achieve either an overlapping or a stacking effect.
- The plugin wraps a placeholder div around your target element and matches its height. This keeps your content from shifting when the element becomes fixed position and is removed from the page flow.
- It also creates a wrapper around your element to give you another hook for CSS position.
- Optional breakpoint parameter makes it easy to suppress Clingify behavior below a certain screen width for smart phones and tablets.
- Optional callback functions for when the element is attached or detached.
- Optional callback function for when the page is resized. This is helpful for fluid widths and responsive design.
- The window scroll and resize events are throttled to improve performance. The amount of throttle is a configurable option.

## How to use

Just initialize the script somewhere after you’ve included jQuery (1.7+) and the plugin.

Simple:

`

    <script type="text/javascript" src="/js/jquery.js"></script>
    <script type="text/javascript" src="/js/jquery.clingify.js"></script>
    <script type="text/javascript">
    $(function() {
        $('.some-selector').clingify();
    });
    </script>

`

Here are the default settings:

`

    $('.some-selector').clingify({
        breakpoint: 0,  // in pixels
        extraClass: '',
        throttle: 100,  // in milliseconds

        // Callback functions:
        detached: $.noop,
        locked: $.noop,
        resized: $.noop
    });

`

Example with callback functions:

`

    $(function() {
        var $clingifyTarget = $('.some-selector'),
            $parent = $('.some-fluid-width-parent-container'),
            matchWidths = function($elem) {
                $elem.width($parent.width());
            };

        $clingifyTarget.clingify({
            locked : function() {
                matchWidths($clingifyTarget);
            },
            resized : function() {
                matchWidths($clingifyTarget);
            }
        });
    });

`

A version of the above example is being used on this page to keep the width of the clingy nav aligned with the main content. (Try resizing the browser window.)

## Options

(If table data is cut off, scroll left or right.)

Propery | Value Types | Default | Notes
--- | --- | --- | ---
breakpoint | integer | 0 | At screen sizes narrower than this number (of pixels), suppress Clingify behaviors.
extraClass | string | '' | Add another class to the wrapper and placeholder divs. This allows for different CSS rules for different Clingify elements.
throttle | integer | 100 | How often, in milliseconds, to check for scroll and resize events
detached | function | $.noop | Callback fires just before an element is un-Clingified.
locked | function | $.noop | Callback fires just before an element is Clingified.
resized | function | $.noop | Callback fires just after window is resized.

## Some filler text to force a long, scrolling page

☆ What if there was a second clingy element on the page? ☆ ★ With some thoughtful CSS you can have both! ★

Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo. Quisque sit amet est et sapien ullamcorper pharetra. Vestibulum erat wisi, condimentum sed, commodo vitae, ornare sit amet, wisi. Aenean fermentum, elit eget tincidunt condimentum, eros ipsum rutrum orci, sagittis tempus lacus enim ac dui in turpis pulvinar facilisis. Ut felis.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer nec odio. Praesent libero. Sed cursus ante dapibus diam. Sed nisi. Nulla quis sem at nibh elementum imperdiet. Duis sagittis ipsum. Praesent mauris. Fusce nec tellus sed augue semper porta. Mauris massa. Vestibulum lacinia arcu eget nulla. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Curabitur sodales ligula in libero. Sed dignissim lacinia nunc.

Curabitur tortor. Pellentesque nibh. Aenean quam. In scelerisque sem at dolor. Maecenas mattis. Sed convallis tristique sem. Proin ut ligula vel nunc egestas porttitor. Morbi lectus risus, iaculis vel, suscipit quis, luctus non, massa. Fusce ac turpis quis ligula lacinia aliquet. Mauris ipsum. Nulla metus metus, ullamcorper vel, tincidunt sed, euismod in, nibh.

Quisque volutpat condimentum velit. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Nam nec ante. Sed lacinia, urna non tincidunt mattis, tortor neque adipiscing diam, a cursus ipsum ante quis turpis. Nulla facilisi. Ut fringilla. Suspendisse potenti. Nunc feugiat mi a tellus consequat imperdiet. Vestibulum sapien. Proin quam. Etiam ultrices.

Suspendisse in justo eu magna luctus suscipit. Sed lectus. Integer euismod lacus luctus magna. Quisque cursus, metus vitae pharetra auctor, sem massa mattis sem, at interdum magna augue eget diam. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Morbi lacinia molestie dui. Praesent blandit dolor. Sed non quam. In vel mi sit amet augue congue elementum. Morbi in ipsum sit amet pede facilisis laoreet. Donec lacus nunc, viverra nec, blandit vel, egestas et, augue. Vestibulum tincidunt malesuada tellus. Ut ultrices ultrices enim. Curabitur sit amet mauris. Morbi in dui quis est pulvinar ullamcorper.

Nulla facilisi. Integer lacinia sollicitudin massa. Cras metus. Sed aliquet risus a tortor. Integer id quam. Morbi mi. Quisque nisl felis, venenatis tristique, dignissim in, ultrices sit amet, augue. Proin sodales libero eget ante. Nulla quam. Aenean laoreet. Vestibulum nisi lectus, commodo ac, facilisis ac, ultricies eu, pede. Ut orci risus, accumsan porttitor, cursus quis, aliquet eget, justo. Sed pretium blandit orci.

Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo. Quisque sit amet est et sapien ullamcorper pharetra. Vestibulum erat wisi, condimentum sed, commodo vitae, ornare sit amet, wisi. Aenean fermentum, elit eget tincidunt condimentum, eros ipsum rutrum orci, sagittis tempus lacus enim ac dui in turpis pulvinar facilisis. Ut felis.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer nec odio. Praesent libero. Sed cursus ante dapibus diam. Sed nisi. Nulla quis sem at nibh elementum imperdiet. Duis sagittis ipsum. Praesent mauris. Fusce nec tellus sed augue semper porta. Mauris massa. Vestibulum lacinia arcu eget nulla. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Curabitur sodales ligula in libero. Sed dignissim lacinia nunc.

Curabitur tortor. Pellentesque nibh. Aenean quam. In scelerisque sem at dolor. Maecenas mattis. Sed convallis tristique sem. Proin ut ligula vel nunc egestas porttitor. Morbi lectus risus, iaculis vel, suscipit quis, luctus non, massa. Fusce ac turpis quis ligula lacinia aliquet. Mauris ipsum. Nulla metus metus, ullamcorper vel, tincidunt sed, euismod in, nibh.

Quisque volutpat condimentum velit. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Nam nec ante. Sed lacinia, urna non tincidunt mattis, tortor neque adipiscing diam, a cursus ipsum ante quis turpis. Nulla facilisi. Ut fringilla. Suspendisse potenti. Nunc feugiat mi a tellus consequat imperdiet. Vestibulum sapien. Proin quam. Etiam ultrices.

Suspendisse in justo eu magna luctus suscipit. Sed lectus. Integer euismod lacus luctus magna. Quisque cursus, metus vitae pharetra auctor, sem massa mattis sem, at interdum magna augue eget diam. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Morbi lacinia molestie dui. Praesent blandit dolor. Sed non quam. In vel mi sit amet augue congue elementum. Morbi in ipsum sit amet pede facilisis laoreet. Donec lacus nunc, viverra nec, blandit vel, egestas et, augue. Vestibulum tincidunt malesuada tellus. Ut ultrices ultrices enim. Curabitur sit amet mauris. Morbi in dui quis est pulvinar ullamcorper.

Nulla facilisi. Integer lacinia sollicitudin massa. Cras metus. Sed aliquet risus a tortor. Integer id quam. Morbi mi. Quisque nisl felis, venenatis tristique, dignissim in, ultrices sit amet, augue. Proin sodales libero eget ante. Nulla quam. Aenean laoreet. Vestibulum nisi lectus, commodo ac, facilisis ac, ultricies eu, pede. Ut orci risus, accumsan porttitor, cursus quis, aliquet eget, justo. Sed pretium blandit orci.