Product
Introducing Enhanced Alert Actions and Triage Functionality
Socket now supports four distinct alert actions instead of the previous two, and alert triaging allows users to override the actions taken for all individual alerts.
stickybits
Advanced tools
Readme
Make things get sticky …in a good way
Stickybits is a lightweight alternative to
position: sticky
polyfills. It works perfectly for things like sticky headers.
Stickybits is awesome because:
.js-is-sticky
) when position: sticky elements become active and a CSS Stuck Class (.js-is-stuck
) when they become stuck. See useStickyClasses.position: fixed
have because it tries to support position: sticky
first.scroll
event listener will not be used if position: sticky
is supported.position: sticky
and position: fixed
and it works with them.Installation Setup Usage Feature Options Examples Debugging Notes Contributing Wiki
yarn
yarn add stickybits
npm
npm i stickybits
Add dist/stickybits.min.js
Or as a module with import stickybits from 'stickybits'
stickybits('selector');
Key Note: Stickybits expects and works best when the element that will become sticky is wrapped within a parent element that defines when the element starts being sticky and stops being sticky. See below for visual reference.
<main id="some-stickybit-parent">
<nav id="some-stickybit-nav"></nav>
</main>
useStickyClasses
FeatureStickybits allows customers to add CSS to elements when they become sticky and when they become stuck at the bottom of their parent element.
By default, if position: sticky
is supported, StickyBits will exit allowing the browser to manage stickiness and avoid adding a scroll
event listener.
If the useStickyClasses
argument is set to true
then even if a browser supports position: sticky
, StickyBits will still add a scroll
event listener to add and remove sticky CSS Classes. This option is available so that CSS styles can use when StickyBits elements become sticky or stuck at the bottom of their parent.
To provide more feature richness to the Stickybits experience, a .js-is-sticky--change
CSS class is added after the Stickybit element is sticky for a certain duration of scroll. By default this duration of scrolling is the height of the Stickybit element. The scroll duration for when .js-is-sticky--change
is added can be modified by providing a number for customStickyChangeNumber
option.
To use useStickyClasses
:
stickybits('selector', {useStickyClasses: true});
Then, in css you can do:
.some-sticky-element.js-is-sticky {
background-color: red;
}
.some-sticky-element.js-is-sticky--change {
height: 50px;
}
.some-sticky-element.js-is-stuck {
background-color: green;
}
View add css classes for more information on StickyBits CSS Classes.
By default, a StickyBits element will stick to the top of the viewport when vertically scrolled to.
Stickybits loosely works for bottom
positioning as well.
To have a StickyBits element stick to the bottom
:
stickybits('selector', {verticalPosition: 'bottom'});
By default, if Stickybits uses a scroll event (if position: sticky
is not supported or if we use the option useStickyClasses
) it uses window
.
To have Stickybit use an selector besides window
:
stickybits('selector', {scrollEl: 'an-id'});
* Note: This selector is not selected automatically so the specific element need to be passed in.
By default, a StickyBits element will have a 0px
sticky layout top offset. This means that the element will stick flush to the top of the viewport.
To have a StickyBits element stick with a 20px
offset to its vertical layout position:
stickybits('selector', {stickyBitStickyOffset: 20});
To cleanup an instance of Stickybits:
const stickybitsInstancetoBeCleanedup = stickybits('selector');
stickybitsInstancetoBeCleanedup.cleanup();
To update the calculations of an instance of Stickybits:
const stickybitsInstancetoBeUpdated = stickybits('selector');
stickybitsInstancetoBeUpdated.update();
Re-calculates each Stickybits instance's offsets (stickyStart, stickyStop).
If the Stickybits implementer would like re-calculate offsets when the DOM window is resized or when the url changes. .update()
can be invoked within an event listener.
Examples
// when the window is resized
const stickybitsInstancetoBeUpdated = stickybits('selector');
window.addEventListener('resize' () => {
stickybitsInstancetoBeUpdated.update();
});
// when the url hash changes
window.addEventListener('hashchange' () => {
stickybitsInstancetoBeUpdated.update();
});
Note: .update
does not re-initialize classnames or pre-set calculations.
To use StickyBits without inline styles except for position: sticky
or position: fixed
:
stickybits('selector', {noStyles: true});
To use custom CSS classes for Stickybits, add the appropriate properties and values.
parentClass:
stickybits('selector', {parentClass: 'new-parent-classname'});
stickyClass:
stickybits('selector', {stickyClass: 'new-sticky-classname'});
stuckClass:
stickybits('selector', {stuckClass: 'new-stuck-classname'});
To not use position: sticky
ever, add the following key value to a stickybit initalization..
parentClass:
stickybits('selector', {useFixed: true});
To change all of the CSS classes
stickybits('selector', {
parentClass: 'new-parent-classname',
stickyClass: 'new-sticky-classname',
stuckClass: 'new-stuck-classname',
stickyChangeClass: 'new-sticky-change-classname'
});
* For jQuery and Zepto support, read the jQuery notes below.
stickybits('selector', {stickyBitStickyOffset: 20})
stickybits('selector', {useStickyClasses: true})
const stickything = stickybits('selector'); stickything.cleanup();
const stickything = stickybits('selector') stickything.update()
const stickything = stickybits('selector', {useFixed: true})
$('selector').stickybits()
stickybits('selector', {noStyles: true});
stickybits('selector', {parentClass: 'js-parent-test'})
stickybits('selector', {scrollEl: 'a-custom-scroll-el'})
or stickybits('selector', {scrollEl: element})
Have another example or question? Feel free to comment. 🙌
3 CSS classes will be added and removed by Stickybits if position: sticky
is not supported or if the useStickyClasses: true
option is added to the plugin call. These Classes can be modified as desired. See the With Custom Classes example above.
js-is-sticky
if the selected element is sticky.js-is-stuck
if the selected element is stopped at the bottom of its parent.js-stickybit-parent
so that styles can easily be added to the parent of a Stickybits elementStickybits is not a Shim or Polyfill for position: sticky
because full support would require more code. This plugin makes elements vertically sticky very similarly to position: fixed
but in a sticky
sort of way. Read more about position sticky here or follow its browser implementation here.
Stickybits is a no dependency JavaScript plugin. It provides the smallest API possible in both features and kb size to deliver working sticky elements. This means that opinionated featuring is left out as much as possible and that it works with minimal effort in Frameworks.
position: sticky
is not supportedSticky Start and Sticky Stop: Because Stickybits is minimal, when position: sticky
is not supported Stickybits will use position: fixed
which is relative to the browser window. If the StickyBits parent element has a height recognized by the browser, Stickybits will take care of the sticky top and sticky bottom invocation. If the parent's height is not recognized by the browser there will be issues.
Left and Right Positioning: With position: fixed
the Stickybit element will work relative to the browser window by default. To work with this issue, there are several options. Some are noted here. More solutions to come!
Basic
$('selector').stickybits();
With scrollEl
$('selector').stickybits({scrollEl: '#scrollEl'});
// or
const el = document.querySelector('#scrollEl');
$('selector').stickybits({scrollEl: el});
With .update
var instance = $('selector').stickybits();
instance.update();
With useStickyClasses
$('selector').stickybits({useStickyClasses: true});
With verticalPosition
$('selector').stickybits({verticalPosition: 'bottom'});
With stickyBitStickyOffset
$('selector').stickybits({stickyBitStickyOffset: 20});
Stickybits 2.0 provides the same API but with more debugging feedback.
To view the Stickybits API in it's simpliest form:
var stickybit = stickybits('a selection')
console.log(stickybit)
For more debugging and managing Stickybits, view the wiki.
Stickybits provides both version
and userAgent
properties which were added to offer insight into the browser and Stickybits.
These utility properties can be accessed as direct child properties of the instantiated Stickybits item.
var stickybit = stickybits('a selection')
stickybit.version // will show the version of stickybits being used
stickybit.userAgent // will show which userAgent stickybits is detecting
Stickybits works in all modern browsers including Internet Explorer 9 and above. Please file and issue with browser compatibility quirks.
Please contribute to Stickybits by filing an issue, responding to issues, adding to the wiki, or reaching out socially—etc.
Stickybits is a utility. It may often not be needed! With shared understanding of position: sticky
and position: fixed
along with product awareness, Stickybits can improve as can a shared understanding of the "sticky element issue". Is this paragraph over-reaching? Yes! Help improve it.
This plugin was heavily influenced by Filament Group's awesome Fixed-sticky jQuery plugin. Thanks to them for getting my mind going on this a while back. Thanks to Peloton Cycle's Frame Throttle for an insightful solve for optimizing frame throttling
.
Architecture discussions and Pull Request help has been provided by Jacob Kelley, Brian Gonzalez, and Matt Young. It is much appreciated!
Created and maintained by Jeff Wainwright with Dollar Shave Club Engineering.
FAQs
Stickybits is a lightweight alternative to `position: sticky` polyfills
The npm package stickybits receives a total of 40,225 weekly downloads. As such, stickybits popularity was classified as popular.
We found that stickybits demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Socket now supports four distinct alert actions instead of the previous two, and alert triaging allows users to override the actions taken for all individual alerts.
Security News
Polyfill.io has been serving malware for months via its CDN, after the project's open source maintainer sold the service to a company based in China.
Security News
OpenSSF is warning open source maintainers to stay vigilant against reputation farming on GitHub, where users artificially inflate their status by manipulating interactions on closed issues and PRs.