Scrollbar

A custom scrollbar component. Supports both window and HTMLElement containers.

note

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 CodePen:

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 false, the scrollbar is appended directly to the container. For proper behavior, use parent when applying the scrollbar to an HTML element.	false | HTMLElement	false
class	Custom CSS class to be applied to the scrollbar track. If false, no additional class is applied.	string | false	false
axis	Defines the scrolling axis for the scrollbar. 'x' for horizontal scrolling. 'y' for vertical scrolling.	'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

note

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

note

All Module's methods are available in this class.

resize

Force-resize the scrollbar.

instance.resize();

Callbacks

note

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();