Top

Usage

Pinning an element to stay within the viewport or within a parent, during a resize or scroll, is especially handy for side navigation, or top bar menus. Simply initialize a pin on the element we want pinned.

$('.pin').pin();

Animations

By default, no animations are set on the pinned element. This will cause choppiness while scrolling unless the throttle is lowered. To solve this, set an animation, either sticky or slide.

$('.pin').pin({
    animation: 'slide'
});

A slide animation will slowly animate to the new coordinates. A sticky animation will do the same, but will "bounce" before animating.

The .pin class is required for animations to work correctly.

Bounding Container

A pinned element will be bound within its parent element, which means it wont overflow outside the parent. To change the container, set the context option.

$('.pin').pin({
    animation: 'sticky',
    context: '#container'
});
The container requires position relative.

Notes

  • An .is-pinned class will be toggled when the pinned element re-positions.
Top

ARIA

The complementary role and the appropriate aria-* attributes are required when supporting ARIA.

<aside class="pin" role="complementary">
    ...
</aside>
The JavaScript component will automatically map all ARIA attributes.
Top

Variables

Variable Default Description
$pin-class .pin CSS class name for the pinned element.
$pin-transition .2s The transition time for pinned element position animations.
Top

Options

Inherits all options from the parent Component.

Option Type Default Description
animation string The type of animation to use when scrolling down the page. Accepts slide, sticky, or an empty value.
calculate bool false Re-calculate offsets, widths, heights, and viewport while scrolling. May slow down the page while active, so trigger calculate() manually when needed.
fixed bool false Whether to use position fixed or not while scrolling. Fixed pins will not animate.
location string right The horizontal location to use when positioning. Accepts left or right.
lock bool true Whether to deactivate pinning if the target element is larger than the viewport.
throttle int 50 The time in milliseconds to throttle the page scroll events.
xOffset int 0 The offset in pixels to move the pin along the X axis.
yOffset int 0 The offset in pixels to move the pin along the Y axis.
Top

Events

Inherits all events from the parent Component.

Event Arguments Description
pinned Triggered when the element is positioned.
resize Triggered when the page is resized, and after calculations have been executed.
scroll Triggered when the page is scrolled, and after the pin has been positioned.
unpinned Triggered when the element is reset to its original state.
Top

Properties

Inherits all properties from the parent Component.

Property Type Description
active bool Will the element be pinned? Depends on the heights of the parent and element.
elementHeight int The height of the pinned element.
elementTop int The initial top offset value of the element.
parentHeight int The height of the parent element.
parentTop int The initial top offset value of the parent element.
pinned bool Whether the element is positioned or not.
initialTop int The CSS top value of the element.
viewport object The current width and height of the viewport (window object).
Top

Methods

Inherits all methods from the parent Component.

Method Description
calculate() Calculate the dimensions and offsets of elements used by the pin.
pin() Pin the element based on the current parent and element dimensions and the position of the scroll.
unpin() Unpin the element and reset position to its original state.