Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/stefangabos/zebra_pin
A lightweight and adaptive jQuery plugin for creating sticky elements pinned to the page or to a container element
https://github.com/stefangabos/zebra_pin
fixed pinned pinned-elements sticky sticky-elements sticky-header sticky-sidebar
Last synced: 9 days ago
JSON representation
A lightweight and adaptive jQuery plugin for creating sticky elements pinned to the page or to a container element
- Host: GitHub
- URL: https://github.com/stefangabos/zebra_pin
- Owner: stefangabos
- License: other
- Created: 2013-12-07T18:57:50.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2024-04-22T06:09:10.000Z (7 months ago)
- Last Synced: 2024-04-23T09:50:05.568Z (7 months ago)
- Topics: fixed, pinned, pinned-elements, sticky, sticky-elements, sticky-header, sticky-sidebar
- Language: JavaScript
- Homepage: https://stefangabos.github.io/Zebra_Pin/
- Size: 760 KB
- Stars: 67
- Watchers: 6
- Forks: 16
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
README
# Zebra Pin [](https://twitter.com/intent/tweet?text=A+lightweight+jQuery+plugin+for+creating+sticky+elements+pinned+to+the+page+or+to+a+container+element&url=https://github.com/stefangabos/Zebra_Pin&via=stefangabos&hashtags=jquery,javascript,pin,sticky,pinned)
*A lightweight and adaptive jQuery plugin for creating sticky elements pinned to the page or to a container element*
[](https://www.npmjs.com/package/zebra_pin) [](https://www.npmjs.com/package/zebra_pin) [](https://www.npmjs.com/package/zebra_pin) [](https://www.jsdelivr.com/package/npm/zebra_pin) [](https://github.com/stefangabos/Zebra_Pin/blob/master/LICENSE.md)
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+
## 🎂 Support the development of this project
Your support means a lot and it keeps me motivated to keep working on open source projects.
If you like this project please ⭐ it by clicking on the star button at the top of the page.
If you are feeling generous, you can buy me a coffee by donating through PayPal, or you can become a sponsor.
Either way - **Thank you!** 🎉
[
](https://github.com/stefangabos/Zebra_Pin) [](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=K8HEUNMPV65R4) [
](https://github.com/sponsors/stefangabos)
## Demo
See the [demos](https://stefangabos.github.io/Zebra_Pin/)
## Requirements
Zebra Pin has no dependencies other than jQuery 1.7+
## Installation
Zebra Pin is available as a [npm package](https://www.npmjs.com/package/zebra_pin). To install it use:
```bash
# the "--save" argument adds the plugin as a dependency in packages.json
npm 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:
```html
window.jQuery || document.write('<script src="path/to/local/jquery-3.7.0.js"><\/script>')
```
Load the Zebra Pin jQuery plugin:
```html
```
Alternatively, you can load Zebra Pin from [JSDelivr CDN](https://www.jsdelivr.com/package/npm/zebra_pin) like this:
```html
```
Now, within the DOM-ready event, pin elements to page or to a container:
```javascript
$(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 as argument the element that was pinned
onUnpin
Callback function to be executed when an element becomes unpinned (reverts to its original state)
The callback function receives as argument the element that was unpinned
## 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.*
```javascript
// 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();
```
### `destroy()`
Destroys the plugin and removes the pinning functionality from the elements the plugin was attached to.
```javascript
// initialize the plugin
var zp = new $.Zebra_Pin($('#element'));
// destroy the plugin, removing the functionality from the elements it was associated with
zp.destroy();
```
## Sponsors
Cross browser/device testing is done with
[](https://www.browserstack.com/)