Scrollbar
A custom scrollbar component. Supports both window
and HTMLElement
containers.
To prevent layout shifts, hide native scrollbars in your CSS:
.your_container {
-ms-overflow-style: none;
scrollbar-width: none;
&::-webkit-scrollbar {
display: none;
appearance: none;
width: 0;
height: 0;
}
}
Examples
Explore live examples in CodeSandbox:
Body Scrollbar
Inner Scrollbar
Horizontal Scrollbar
Props
Static Props
Static properties are set during initialization and cannot be modified later.
Name | Description | Type | Default Value |
---|---|---|---|
container | The element to which the scrollbar is applied. Can be either the window or a specific HTML element. | Window | HTMLElement | window |
parent | The parent element where the scrollbar should be appended. If For proper behavior, use | false | HTMLElement | false |
class | Custom CSS class to be applied to the scrollbar track. If | string | false | false |
axis | Defines the scrolling axis for the scrollbar.
| 'x' | 'y' | 'y' |
draggable | Determines whether the scrollbar thumb is draggable. | boolean | true |
autoHide | Automatically hides the scrollbar when inactive. | boolean | true |
resizeDebounce | Debounce time (in milliseconds) for handling resize events. Helps improve performance by limiting the frequency of resize calculations. | number | 0 |
Mutable Props
Mutable properties can be updated at runtime using .updateProps()
.
Name | Description | Type | Default Value |
---|---|---|---|
minSize | Minimum size of the scrollbar thumb. Accepts numeric values (interpreted as pixels) or CSS units (px , rem , vw , vh , svh ). | number | string | 50 |
autoSize | Enables automatic adjustment of the scrollbar size. | boolean | true |
Accessors
All Module's accessors are available in this class.
axis
Type: "x" | "y"
Scrolling direction
container
Type: Window | HTMLElement
The element to which the scrollbar is applied.
outer
Type: HTMLElement
Scrollbar outer element
parent
Type: HTMLElement
The element where the scrollbar is appended. If parent
is not set, it defaults to container
or document.body
(if applied to window
).
scrollableSize
Type: number
Returns the total scrollable distance.
scrollElement
Type: HTMLElement
The actual scrollable element. Returns document.documentElement
for window
, otherwise the container
itself.
scrollSize
Type: number
Returns the total scroll width/height of the content.
scrollValue
Type: number
Returns scrollTop or scrollLeft of the scrollable element.
thumb
Type: HTMLElement
Scrollbar thumb element (draggable handle).
thumbSize
Type: number
Returns the current thumb size.
track
Type: HTMLElement
Scrollbar track element (the container of the thumb).
trackSize
Type: number
Returns the current track size.
Methods
All Module's methods are available in this class.
resize
Force-resize the scrollbar.
instance.resize();
Callbacks
All Module's callbacks are available in this class.
update
Triggered when the scrollbar updates its position.
const destruct = instance.on('update', () => console.log('update'));
// Cancel the callback
destruct();
resize
Triggered when the scrollbar resizes.
const destruct = instance.on('resize', () => console.log('resize'));
// Cancel the callback
destruct();
show
Triggered when the scrollbar is shown
const destruct = instance.on('show', () => console.log('show'));
// Cancel the callback
destruct();
hide
Triggered when the scrollbar is hidden
const destruct = instance.on('hide', () => console.log('hide'));
// Cancel the callback
destruct();
swipeStart
Triggered on swipe start
const destruct = instance.on('swipeStart', (coords) => console.log(coords));
// Cancel the callback
destruct();
swipe
Triggered on swipe move
const destruct = instance.on('swipe', (coords) => console.log(coords));
// Cancel the callback
destruct();
swipeEnd
Triggered on swipe end
const destruct = instance.on('swipeEnd', (coords) => console.log(coords));
// Cancel the callback
destruct();