Free, easy to use, javascript library for toggling between original and fixed position, because of limited support of sticky position even in newer browsers.
Current stable version: 2.7.1
Jquery.smartSticky supports:
- Highly customizable visibility and placement of the element
- Toggling between top and bottom position
- Displaying of fixed element only inside of container area
- Implementation of own callbacks and positions
- Support of fixed header in tables
SmartSticky is built on and works properly with jQuery.
Include the following code in the <head> tag of your HTML:
<!-- include jQuery -->
<script type="text/javascript" src="//cdnjs.cloudflare.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>
<!-- include jquery.smartSticky css/js-->
<link rel="stylesheet" href="/dist/css/jquery.smartSticky.min.css">
<script type="text/javascript" src="/dist/js/jquery.smartSticky.min.js"></script>$('#myElem').smartSticky([options])- options (optional)
- Type:
Object - Default options to be changed, see the list of available options below.
- Type:
You can use the following code with default options.
null properties are computed automatically by library.
$(function() {
$('#myElem').smartSticky({
show: {
immediately: false,
delay: 50, /* ignored when immediately set to true */
original: {
under: true,
above: false
},
fixed: 'top',
scrolling: {
up: true,
down: true
}
},
container: null,
css: {
fixed: {
width: null,
left: null
}
}
});
});- Type:
Number - Default:
50
ScrollTop value that postpones showing of the fixed element and accelerates its hiding on return. Use 0 to deactivate.
- Type:
Boolean - Default:
false
Determines if the element becomes fixed immediately when its original position is reached. If set to 'true' option 'show.delay' is ignored.
- Type:
Boolean - Default:
false
Determines if the element can be shown above its original position.
- Type:
Boolean - Default:
true
Determines if the element can be shown under its original position.
- Type:
String - Default:
'top'
Determines placement of the fixed element.
Possible predefined values are 'top', 'bottom' and 'toggle'.
'toggle' places fixed element top while scrolling down and bottom while scrolling up. If used, options show.scrolling.up and show.scrolling.down should be set to true, eventually, callback show.scrolling should return true for properly behaviour.
If you want to define your own placement position callback, extend default positions object like with the following code:
$.fn.smartSticky.positions['myAwesomePosition1'] = function (positionManager) {
if (positionManager.getScrollingManager().scrollingDown()) {
return { top: 10 };
}
return { bottom: 10 };
};
$.fn.smartSticky.positions['myAwesomePosition2'] = function () {
if ($(window).outerWidth() < 900) {
return { bottom: 0 };
}
return 'toggle';
};
// change options
show: {
fixed: 'myAwesomePosition1'
}This callback can be used in two different ways:
- return
Objectwith extra'top'or'bottom'. - return
Stringwith name of other defined position to apply.
- Returns:
String
One of the accepted values of show.fixed option property.
show: {
fixed: function () {
if ($(window).width() < 768) {
/* on mobile phones */
return 'bottom';
}
return 'toggle';
}
}- Type:
Boolean - Default:
true
Determines if the fixed element can be shown while scrolling up.
If show.fixed is set to 'toggle', this option should be set to true for properly behaviour.
- Type:
Boolean - Default:
true
Determines if the fixed element can be shown while scrolling down.
If show.fixed is set to 'toggle', this option should be set to true for properly behaviour.
- Returns:
Boolean
Determines visibility of the fixed element while scrolling.
Use true to show and false to hide.
If show.fixed is set to 'toggle', this callback should return true for properly behaviour.
show: {
scrolling: function (settingsManager, scrollingManager) {
if ($(window).width() < 768) {
/* on mobile phones */
return !scrollingManager.scrollingDown();
}
return scrollingManager.scrollingDown();
}
}- Type:
HTMLelement,HTMLCollection,JQueryorString - Default:
null
The fixed element can be displayed only inside of container area.
By default, the element's original parent is used.
Use String to find element by selector.
If more elements are included in JQuery collection or if they are found by String selector, first element is used.
If no element is included in JQuery collection or found by String selector, default container is used.
- Returns:
HTMLelement,HTMLCollection,JQueryorString
container: function (settingsManager) {
/*
<div class="row">
<div class="col-3">
<div class="sticky-smart"></div>
</div>
<div class="col-9">
....
</div>
</div>
*/
return settingsManager.getElement().closest('.row');
}- Type:
NumberorString - Default:
null
By default, the element's offset left in original position is used.
Sets css left property of the fixed element.
- Type:
NumberorString - Default:
null
By default, the element's outer width in original position is used.
Sets css width property of the fixed element.
- Return
NumberorString
Set css left and width property of the fixed element.
If you want to change top or bottom property of the fixed element, define your own placement position callback as described above.
css: {
fixed: {
left: function (settingsManager) {
if ($(window).width() < 768) {
/* on mobile phones */
return 0;
}
return settingsManager.getElement().offset().left;
},
width: function (settingsManager) {
if ($(window).width() < 768) {
/* on mobile phones */
return '100%';
}
return settingsManager.getElement().outerWidth();
}
}
}smartSticky library works with the following managers which are provided in callbacks as arguments. You can access their methods (getters and boolean queries) to find out useful information.
Attention: Using of other manager's methods then listed below (etc. private setters), or modifying its private underline properties can cause unexpectable behaviour.
- Type:
Object - Methods:
getElement(),getContainer()andgetOptions()
- Type:
Object - Methods:
scrollingDown()andgetCurrentScrollTop()
- Type:
Object - Methods:
getSettingsManager(),getScrollingManager(),getFixedPosition()andgetYCoordManager()
If you want to change default settings, use the following code:
$.extend( true, $.fn.smartSticky.defaults, {
show: {
delay: 0
}
} );Use only after initialization.
$('.myElems').smartSticky('methodName', argument1, argument2, ...);
/* or */
$('.myElems').each(function () {
$(this).smartSticky('instance').methodName(argument1, argument2, ...);
});Updates dynamically options.
$('#myElem').smartSticky('setOptions', {
show: {
scrolling: {
up: true
}
}
});Enables component.
Disables component.
Hides fixed element until it is about to be shown again.
Use the following code to set callback on event. Set them before smartSticky initialization.
$('#myElem').on('smartSticky.eventName', function (e, settingsManager) {
}).smartSticky();Fires when element's fixed position is going to be set.
$('#myElem').on('smartSticky.activate', function (e, settingsManager) {
$(this).css('border', '1px solid black');
}).smartSticky();Fires when element's original position is going to be set.
Fires immediately after element had been activated.
Fires immediately after element had been deactivated.
Fires after smart sticky had been fully initialized.
jquery.smartSticky may be freely distributed under the MIT license.