@brybrant/fade-scroll
v2.0.0
Published
Fade Scroll is a cosmetic module which adds subtle gradient masks to the overflow of scrollable content.
Maintainers
brybrantReadme
Fade Scroll
Fade Scroll is a cosmetic module which adds subtle gradient masks to the overflow of scrollable content.
See the demo page for an interactive demonstration.
[!IMPORTANT] Fade Scroll automatically injects the minimal CSS required. The visual fade effect is intentionally left to the user so that it can be customized freely. See fade-scroll.css for example styles which use CSS masks to blend seamlessly with any background. If you want to support legacy browsers, see fade-scroll--legacy.css for an example of how you can use linear gradients with pseudo elements to achieve a similar effect.
Install
$ npm i @brybrant/fade-scrollSetup
<html>
<head>
<link rel='stylesheet' href='fade-scroll.css'/>
</head>
<body>
<div id='horizontal'>
<p>Some horizontal overflowing content...</p>
</div>
<div id='vertical'>
<p>Some vertical overflowing content...</p>
</div>
<script type='module' src='index.js'></script>
</body>
</html>// index.js
import * as FadeScroll from '@brybrant/fade-scroll';
// Constructor with HTMLElement
const horizontal = new FadeScroll.Horizontal(
document.getElementById<HTMLElement>('horizontal')!,
);
// Constructor with string (passed to `document.querySelector()`)
const vertical = new FadeScroll.Vertical('#vertical');
// Lifecycle begin
horizontal.mount();
vertical.mount();
// Set options
horizontal.captureWheel = true;
vertical.hideScrollbar = true;
// Change options
vertical.hideScrollbar = false;
// Lifecycle end
horizontal.destroy();
vertical.destroy();API
The constructor requires only one argument:
HTMLElement or string (which is passed to querySelector())
This will become the content of the Fade Scroller.
The constructor returns a Fade Scroller:
Fade Scroller Properties:
content
The element selected in the first argument of the constructor function
- Type:
HTMLElement - Access:
Read
scrollBar
The element with overflow (contains content element)
- Type:
HTMLDivElement - Access:
Read
wrapper
The outer element (contains scrollBar element)
- Type:
HTMLDivElement - Access:
Read
overflowSize
The size of the overflow
- Type:
number - Access:
Read
|Horizontal|Vertical|
|-|-|
|content width minus wrapper width|content height minus wrapper height|
scrollPosition
The scroll position of the scrollBar element
- Type:
number - Access:
Read / Write
|Horizontal|Vertical|
|-|-|
|scrollLeft|scrollTop|
hideScrollbar
Hide the scrollbar?
- Type:
boolean - Default:
false - Access:
Write
captureWheel (Horizontal only)
Capture wheel events and translate vertical to horizontal scroll movement?
- Type:
boolean - Default:
false - Access:
Write
Fade Scroller Methods:
mount()
- Adds the FadeScroll CSS classes.
- Adds wrapper and scrollBar to the DOM.
- Moves content to inside the scrollBar element.
- Starts observing content and wrapper elements.
- Adds the internal scroll event listener to scrollBar.
This will begin to add or remove CSS classes on the wrapper element in response to scrolling or size changes.
[!TIP] The
mount()method returnsthisso you can construct a new Fade Scroller and then immediately mount it in a single assignment:const scroller = new FadeScroll.Horizontal('.selector').mount(); console.log(scroller instanceof FadeScroll.Horizontal); // true
destroy()
- Removes the internal scroll event listener from scrollBar.
- Stops observing content and wrapper elements.
- Removes the FadeScroll CSS classes.
- Moves the content element to its original position in the DOM.
- Removes wrapper and scrollBar from the DOM.
[!TIP] A destroyed Fade Scroller can be mounted again by calling
mount()
Browser Compatibility
The Fade Scroll demo uses CSS masks, but you may use linear gradients for better compatibility if the background is a solid color.
Fade Scroll requires the ResizeObserver API. Browsers without native support must provide a ponyfill using setResizeObserver() before constructing any scrollers:
import { ResizeObserver as Ponyfill } from '@juggle/resize-observer';
import * as FadeScroll from '@brybrant/fade-scroll';
FadeScroll.setResizeObserver(Ponyfill);
// Create some Fade Scrollers **after** setting the ponyfill...