attach - arguments

Possible arguments that can be used in attach method.

bar

General settings for scrollbar "bar" thickness and offset.

^{_{Default value}}

bar: {
  y: {
    width: 6,
    offset: [0, 0],
  },
  x: {
    height: 6,
    offset: [0, 0],
  },
},

^_Type

bar?: BarConfig;

export type BarConfig = {
  y?: {
    width?: number;
    offset?: [number, number];
  };
  x?: {
    height?: number;
    offset?: [number, number];
  };
};

enableRail

Shows a rail - the background track under the scrollbar thumb. The rail is an optional plugin, so it has to be passed in plugins as well; without it enableRail only logs a warning. See the Rail example.

import { rail } from "@frsource/light-scrollbar/rail";
import "@frsource/light-scrollbar/dist/rail.css";

attach(el, { enableRail: true, plugins: [rail] });

^{_{Default value}}

enableRail: false,

^_Type

enableRail?: boolean;

rail

Rail thickness and offset, same shape as bar. Every value that is not set is taken from bar, so with enableRail alone the rail has exactly the size and position of the scrollbar. Used only when enableRail is on.

MOUSE AREA

With the rail on, the whole rail reacts to the mouse like the scrollbar does: hovering, clicking and dragging work anywhere on the rail, also when it is thicker than the scrollbar or placed with a different offset. A click away from the thumb jumps the thumb there. When both rails are visible, the corner where they cross is sized by the thicker of the rail and the scrollbar, and the scrollbar stops where the rail ends.

^{_{Default value}}

values of bar

^_Type

// every value that is not set is taken from `bar`
rail?: BarConfig;

export type BarConfig = {
  y?: {
    width?: number;
    offset?: [number, number];
  };
  x?: {
    height?: number;
    offset?: [number, number];
  };
};

plugins

Optional features that live in separate entries, so they are added to your bundle only when you import them. Currently available: rail from @frsource/light-scrollbar/rail.

^{_{Default value}}

plugins: [],

^_Type

plugins?: LightScrollbarPlugin[];

export type PluginContext = {
  config: InternalConfig;
  innerElement: HTMLElement;
  outerElement: HTMLElement;
};

export type PluginAxisUpdate = {
  // whether the scrollbar of this axis is shown (content overflows the container)
  visible: boolean;
  // length of the track the thumb moves along - the container edge without the corner,
  // when both scrollbars are visible
  length: number;
};

export type PluginUpdate = {
  x: PluginAxisUpdate;
  y: PluginAxisUpdate;
};

// a strip along the container edge, like `bar`: `size` - thickness, `offset` - distance from the edge
export type PluginHitArea = {
  size: number;
  offset: number;
};

export type PluginInstance = {
  // additional strips that react to the mouse like the scrollbar does (hover, press, drag);
  // the corner where both scrollbars cross is sized by the thickest strip of the other axis
  hitArea?: Partial<Record<Axis, PluginHitArea>>;
  // called whenever the scrollbars are recalculated (resize, content change)
  update?: (state: PluginUpdate) => void;
  // called on `detach()`, before the original DOM structure is restored
  detach?: () => void;
};

export type LightScrollbarPlugin = {
  name: string;
  // called once by `attach()`; return nothing to stay inactive for this instance
  setup: (context: PluginContext) => PluginInstance | void;
};

className

ClassName used to target HTMLElement that has overflow: auto on it, meaning is scrollable container.

^{_{Default value}}

className: "light-scrollbar",

^_Type

className?: string;

disableFocusPrevent

By default emitting focus event is disabled, means when scroll is initialized from this container no focus event will be emitted.

^{_{Default value}}

disableFocusPrevent: true,

^_Type

disableFocusPrevent?: boolean;

wrapperPlacement

In order to create custom scrollbar, at this moment only possible solution is to wrap scrollable container with wrapper. This plugin can create wrapper inside your container and switch node and its all classes/attrs/listeners from original container to inner child, or create outside wrapper.

^{_{Default value}}

wrapperPlacement: WrapperPlacement.inside,

^_Type

wrapperPlacement?: WrapperPlacement;

export enum WrapperPlacement {
  "inside" = "inside",
  "outside" = "outside",
}

wrapperElement

There is possibility to create wrapper element from given HTMLElement passed via this parameter.

^{_{Default value}}

null

^_Type

wrapperElement?: HTMLElement;

showOnHover

Scrollbars can be visible only when hover on container.

^{_{Default value}}

showOnHover: false,

^_Type

showOnHover?: number | false