Sticky Sidebar 😎
Sticky Sidebar ⬆⬇ is a pure JavaScript plugin for making smart and high performance sticky sidebar, works with sidebar if it’s taller or shorter than the viewport, integrated with resize sensor to re-calculate the dimensions automatically when the size of sidebar or its container is changed, supports jQuery/Zepto and compatible with Firefox, Chrome, Safari, and IE9+. Source can be found on Github.
- Why sticky sidebar is awesome?
- Examples
- Installation
- Usage
- Configure Your CSS
- Options
- Events
- Public Methods
- Scrolling Performance
- Browser Compatibility
- jQuery/Zepto No Conflict
Why sticky sidebar is awesome?
- It does not re-calculate all dimensions when scrolling, just neccessary dimensions.
- Super smooth without incurring scroll lag or jank and no page reflows.
- Integrated with resize sensor to re-calculate all dimensions of the plugin when the size of sidebar and its container is changed.
- It has event trigger on each affix type to hook your code under particular situations.
- Handle the sidebar when it is tall or too short compared to the rest of the container.
- Zero dependencies and super simple to setup.
Examples
Basic
Just call new StickySidebar('ELEMENT') on the element that you want it to be sticky when scrolling up/down inside their parent.
var sidebar = new StickySidebar('#sidebar', {topSpacing: 20});Scrollable Sticky Element
Sticky sidebar is smart enough to handle sidebar when it’s taller than the viewport. You don’t have to worry about content, it will scroll the sidebar independently, up and down.
var sidebar = new stickySidebar('#sidebar', {topSpacing: 20});Installation
You can install sticky sidebar plugin from Bower, NPM or just simply download it from GitHub then put sticky-sidebar.js file into your project folder.
Bower
If you are using Bower as package manager:
bower install sticky-sidebar
NPM
If you are using NPM as package manager:
npm install sticky-sidebar
Usage
Your website’s HTML structure has to be similar to this in order to work:
<div id="main-content" class="main">
<div id="sidebar" class="sidebar">
<div class="sidebar__inner">
<!-- Content goes here -->
</div>
</div>
<div id="content" class="content">
<!-- Content goes here -->
</div>
</div>Note that inner sidebar wrapper .sidebar__inner is optional but highly recommended, if you don’t write it yourself, the script will create one for you under class name inner-wrapper-sticky, but this may cause many problems.
For the above example, you can use the following JavaScript:
<script type="text/javascript" src="./js/sticky-sidebar.js"></script>
<script type="text/javascript">
var sidebar = new StickySidebar('#sidebar', {
containerSelector: '#main-content',
innerWrapperSelector: '.sidebar__inner',
topSpacing: 20,
bottomSpacing: 20
});
</script>Usage with jQuery/Zepto
You can configure sticky sidebar as a jQuery plugin, just include jquery.sticky-sidebar.js instead of sticky-sidebar.js file than configure it as any jQuery plugin.
$('#sidebar').stickySidebar({
topSpacing: 60,
bottomSpacing: 60
});Make sure to include jquery.sticky-sidebar.js script file after jquery.js.
Usage with ResizeSensor.js
Integrate ResizeSensor.js into sticky sidebar to detect when sidebar or container is changed. To use resize sensor with this plugin just make sure to include ResizeSensor.js before sticky-sidebar.js code whether through module loader, bundle or event inclusion as a <script> and enable resizeSensor option (enabled by default) and it will work.
If you choose not to include ResizeSensor.js, sticky sidebar will not have automatic resize detection and still continue to work without any problem.
Configure Your CSS
Next you are going to need some CSS just to improve performance and prevent repainting on scrolling. Sticky sidebar plugin doesn’t add below styles as inline so you need to add them manually in your stylesheet.
.sidebar{
will-change: min-height;
}
.sidebar__inner{
transform: translate(0, 0); /* For browsers don't support translate3d. */
transform: translate3d(0, 0, 0);
will-change: position, transform;
}Options
Sticky sidebar plugin comes with options to configure how it works. All options below are optional. Default values are presented below.
var stickySidebar = new StickySidebar('#sidebar', {
topSpacing: 0,
bottomSpacing: 0,
containerSelector: false,
innerWrapperSelector: '.sidebar__inner',
resizeSensor: true,
stickyClass: 'is-affixed',
minWidth: 0
});topSpacing
Additional top spacing of the element when it becomes sticky. Default: 0.
var sidebar = new StickySidebar('.sidebar', {topSpacing: 50});bottomSpacing
Additional bottom spacing of the element when it becomes sticky. Default: 0.
var sidebar = new StickySidebar('.sidebar', {bottomSpacing: 50});containerSelector
Specify a container sidebar to limit the begin and end points of sticky element. Defaults to the closest parent of the sticky element. It is highly recommended to specify a container selector.
var sidebar = new StickySidebar('.sidebar', {containerSelector: '.container'});innerWrapperSelector
Inner wrapper selector of sticky sidebar, if this wrapper is not found inside sidebar element, the plugin will create one for you under class name inner-wrapper-sticky. It is highly recommended to write inner wrapper of sidebar yourself than add its selector to this option. Default: .inner-wrapper-sticky.
var sidebar = new StickySidebar('.sidebar', {innerWrapperSelector: '.sidebar__inner'});resizeSensor
If sticky sidebar has ResizeSensor.js integrated, when the size of sidebar or its container element is changed the plugin will re-calculate all dimensions. This option allows you to enable or disable resize sensor feature. Default: true.
Note: This option won’t work even ResizeSensor.js is included into your page, more details in Usage with ResizeSensor.js section.
var sidebar = new StickySidebar('.sidebar', {resizeSensor: true});stickyClass
The name of CSS class which will be added to the sidebar element when it becomes sticky. Default: is-affixed.
var sidebar = new StickySidebar('.sidebar', {stickyClass: 'is-affixed'});minWidth
The sidebar returns to its normal position when the width of window is below this value. Default: 0.
var sidebar = new StickySidebar('.sidebar', {minWidth: 300});Events
Sticky sidebar plugin has various events which are triggered when affix state changes.
affix.top.stickySidebar — Fires immediately before the element has been affixed to the top of the viewport.
affixed.top.stickySidebar — Fires immediately after the element has been affixed to the top of the viewport.
affix.bottom.stickySidebar — Fires immediately before the element has been affixed to the bottom of the viewport.
affixed.bottom.stickySidebar — Fires immediately after the element has been affixed to the bottom of the viewport.
affix.container-bottom.stickySidebar — Fires immediately before the element has been affixed to the bottom of the container.
affixed.container-bottom.stickySidebar — Fires immediately after the element has been affixed to the bottom of the container.
affix.unbottom.stickySidebar — Fires immediately before the element is no longer bottomed out.
affixed.unbottom.stickySidebar — Fires immediately after the element is no longer bottomed out.
affix.static.stickySidebar — Fires immediately before the element has returned to its position.
affixed.static.stickySidebar — Fires immediately after the element has returned to its position.
For example if you want to detect when element sticks to top and bottom we might do:
var sidebar = document.getElementById('sidebar');
var stickySidebar = new StickySidebar(sidebar);
sidebar.addEventListener('affix.top.stickySidebar', function () {
console.log('Sidebar has stuck top of viewport.');
});
sidebar.addEventListener('affix.bottom.stickySidebar', function (event) {
console.log('Sidebar has stuck bottom of viewport.');
});Public Methods
updateSticky - Force re-calculation of all cached dimensions of sidebar, container and viewport and update position of sidebar according to the new dimensions. The same function of trigger event update.sticky, read about events above.
var stickySidebar = new StickySidebar('.sidebar');
stickySidebar.updateSticky();destroy - remove all inline styles, helper classes and event listeners.
var stickySidebar = new StickySidebar('.sidebar');
stickySidebar.destroy();Scrolling Performance
Sticky sidebar plugin takes scrolling preformance very seriously, It’s built from the ground up to let you have sticky elements without incurring scroll lag or jank.
The biggest cause of scrolling jank is onScroll has a lot of work. But in this plugin we cached all dimensions as well as adding will-change: transform and working with translate(Y, X) instead of top: Y; Left: X; that increased performance significantly, while building Sticky sidebar plugin we prevent repainting and reflow to make it as smooth as possible.
Browser Compatibility
Sticky sidebar works in all modern browsers including Internet Explorer 9 and above, but if you want it to work with IE9, you should include requestAnimationFrame polyfill before sticky sidebar code.
If you have any issue with browser compatibility, don’t hesitate to Submit an issue.
jQuery/Zepto No Conflict
Sometimes sticky sidebar plugin conflicts with other plugins. In this case, namespace collisions can occasionally occur. If this happens, you may call .noConflict on the plugin to revert the value of $.fn.stickySidebar.
var stickySidebar = $.fn.stickySidebar.noConflict(); // Returns $.fn.stickySidebar assigned value.
$.fn.stickySidebar = stickySidebar; // Give $().stickySidebar functionality.Author
Ahmed Bouhuolia GitHub/Facebook/Twitter.