v4 Beta now available! Try it out! Feedback welcome!
Looking for v3 docs?

Affix affix.js

Affix is used to handle the positioning of components based on the scroll position of the window with top and bottom boundaries.

Page Contents

Example #

The 'floating' of the 'top of page' link at the bottom of the screen, is a live demo of the widget.

Usage #

Use the affix widget via data attributes or manually with your own JavaScript. In both situations, you must provide CSS for the positioning of your content.

Positioning via CSS #

The affix widget toggles between three classes, each representing a particular state: .affix, .affix-top, and .affix-bottom. You must provide the styles for these classes yourself (independent of this widget) to handle the actual positions.

Here's how the affix widget works:

  • To start, the widget adds .affix-top to indicate the element is in its top-most position. At this point no CSS positioning is required.
  • Scrolling past the element you want affixed should trigger the actual affixing. This is where .affix replaces .affix-top and sets position: fixed; (provided by Figuration's CSS).
  • If a bottom offset is defined, scrolling past it should replace .affix with .affix-bottom. Since offsets are optional, setting one requires you to set the appropriate CSS. In this case, add position: absolute; when necessary. The widget uses the data attribute or JavaScript option to determine where to position the element from there.

Follow the above steps to set your CSS for either of the usage options below.

Via Data Attributes #

To easily add affix behavior to any element, just add data-cfw="affix" to the element you want to spy on. Use offsets to define when to toggle the pinning of an element.

<div data-cfw="affix" data-cfw-affix-top="60" data-cfw-affix-bottom="200">
...
</div>

Via JavaScript #

Call the affix widget via JavaScript:

$('#myAffix').CFW_Affix({
top: 100,
bottom: function() {
return ($('.footer').outerHeight(true));
}
});

Options #

Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-cfw-affix-, as in data-cfw-affix-top="200".

Name type default description
top number | function 0 Pixel offset from top of the `window` or `target` when calculating position of scroll. Use a function when you need to dynamically calculate an offset.
bottom number | function 0 Pixel offset from bottom of `window` or `target` when calculating position of scroll. Use a function when you need to dynamically calculate an offset.
target selector | node | jQuery element window Specifies the target element of the affix.

Methods #

.CFW_Affix(options) #

Activates an element to be affixed. Accepts an optional options object.

$('#myAffix').CFW_Affix({
top: 10
});

.CFW_Affix('checkPosition') #

Recalculates the state of the affix based on the dimensions, position, and scroll position of the relevant elements. The .affix, .affix-top, and .affix-bottom classes are added to or removed from the affixed content according to the new state. This method needs to be called whenever the dimensions of the affixed content or the target element are changed, to ensure correct positioning of the affixed content.

$('#myAffix').CFW_Affix('checkPosition');

.CFW_Affix('dispose') #

Disables the affix functionality and removes any .affix, .affix-top, or .affix-bottom from the designated element.

Events #

CFW's affix widget exposes a few events for hooking into affix functionality.

Event Type Description
init.cfw.affix This event is fired after the affix element has been initialized.
affix.cfw.affix This event is immediately before after the element is affixed.
affixed.cfw.affix This event is after after the element has been affixed.
affix-top.cfw.affix This event is fired immediately before the element is affixed-top.
affixed-top.cfw.affix This event is fired after the element has been affixed-top.
affix-bottom.cfw.affix This event is immediately before after the element is affixed-bottom.
affixed-bottom.cfw.affix This event is fired after the element has been affixed-bottom.
$('#myAffix').on('affix.cfw.affix', function () {
// do something...
});