mr-scroll

The best custom scroll for the web.

Live demo here.

Features

• Custom and easy to style scrollbar
• Uses the native browser scrollbar behind the scenes -> smooth scrolling, middle mouse click drag works, follows the behavior you're used to
• Behaves exactly like a native scrollbar (detects content size changes, so it's always visually in sync unlike every other custom scrollbar)
• Different modes: scroll, auto, overlay, hidden
• Show on hover
• Hidden content fade (shows a fading effect to indicate there's hidden content out of view)
• Emits various useful events you can handle (scrolled, state changed, position changed, top/bottom reached with configurable thresholds, etc)
  • Great for implementing infinite paging
• Works exactly the same across supported browsers
• Supported on all modern browsers, including mobile browsers

And finally, we have efficient idiomatic wrapper packages for popular frameworks (angular, react, vue2, vue3).

Packages

• @mr-scroll/core: The core package. This does the heavy lifting.
• @mr-scroll/angular: The wrapper package for Angular.
• @mr-scroll/react: The wrapper package for React.
• @mr-scroll/vue2: The wrapper package for Vue 2.
• @mr-scroll/vue: The wrapper package for Vue 3.

Can't find your framework? This means we don't have a wrapper for it just yet. Feel free to suggest/contribute one.

Support packages

We also have support packages:

• @mr-scroll/css-theming: A support package for styling the scrollbar according to the active theme when using css-theming.

All packages in the @mr-scroll org here: https://www.npmjs.com/org/mr-scroll

Config

Check the respective wrapper package and samples for an example usage.

Events

Check the respective wrapper package or sample for an example usage.

Mixins

Defined here.

The @mr-scroll/core package provides several helper mixins in SCSS. You'll always @include the mixins in the direct parent of an mr-scroll.

To use them, you'll import the pure file and include any mixin you want:

@import '@mr-scroll/core/src/scss/pure';

.foo {
  @include msc-[mixin name](...);
}

If you're using the SCSS module system:

@use '@mr-scroll/core/src/scss/pure' as msc;

.foo {
  @include msc.[mixin name](...);
}

As an example, using the height mixin:

@use '@mr-scroll/core/src/scss/pure' as msc;

.my-scroll-parent {
  @include msc.height(200px);
}

Styling

To style mr-scroll in our whole app we can set some global CSS variables. But keep in mind that this sets the styles for all scrolls in the whole hierarchy.

Here is a list of the CSS variables you can override, and their default values:

--mr-scroll-bar-size-normal: 12px;
--mr-scroll-bar-size-overlay: 8px;
--mr-scroll-bar-margin: 3px;
--mr-scroll-track-color: transparent;
--mr-scroll-thumb-border-radius: 2px;
--mr-scroll-thumb-color: #aaa;
--mr-scroll-hidden-content-fade-size: 25px;

Sometimes you want to override a certain style just for one scroll without affecting the others. For that, you can use any of the override-* mixins in that mr-scroll's direct parent:

General usage

Generally, we want to control our scroll in only 3 different ways: fixed height, max height, or fully adaptive. Here is how to do each.

• Fixed height: You'll use the height mixin on the direct parent for mr-scroll (or simply just set a height: ...px; on an .mr-scroll).

• Max height: You'll use the max-height mixin on the direct parent for mr-scroll (or simply just set a max-height: ...px; on an .mr-scroll).

• Adaptive: This is a bit harder to implement when you have a complex layout, but it's still easy. In complex layouts, flexible design doesn't always work well with scrolls. The trick is to use the flex-adaptive-container mixin we provide on parents, all the way up to the root container (or a fixed/absolute container). This will lead to a fully working adaptive layout. For an example of this, check the the full-page page in the angular sample.

Samples

Samples contain working examples of how to use mr-scroll.

• Angular
• React
• Vue 2
• Vue 3

This project follows CCSS for CSS naming conventions.