Class Scrollbar

Configures the given element, which must be scrollable, to use a Scrollbar.

The Scrollbar widget is a customizable alternative to the native scrollbars (vertical and horizontal). You can position each of the two scrollbars on any of the four sides of the element, make them automatically hide after certain time of inactivity, style them as a traditional handle scrollbar or a percentage fill progress bar and so on.

It is also itself draggable/clickable so it can be used to scroll the element similar to the native scrollbar. The drag/click functionality can be disabled too.

NOTE: If you have disabled the PageLoader and have left ScrollbarConfig.hideNative ON, but are seeing the native scrollbars just for a fraction of a second at the beginning of the page load, you may want to manually add lisn-hide-scroll class on the scrollable element to make sure the scrollbars are hidden as soon as possible (before the scrollbar widget has time to initialize.

IMPORTANT: If you are using the Scrollbar on an element other than the main scrollable element, it's highly recommended to enable (it is enabled by default) settings.contentWrappingAllowed.

IMPORTANT: You should not instantiate more than one Scrollbar widget on a given element. Use Scrollbar.get to get an existing instance if any. If there is already a widget instance, it will be destroyed!

You can use the following dynamic attributes or CSS properties in your stylesheet:

The following dynamic attributes are set on the element:

  • data-lisn-has-scrollbar-top: "true" or "false"
  • data-lisn-has-scrollbar-bottom: "true" or "false"
  • data-lisn-has-scrollbar-left: "true" or "false"
  • data-lisn-has-scrollbar-right: "true" or "false"

The following dynamic attributes are set on each progressbar element:

  • data-lisn-orientation: "horizontal" or "vertical"
  • data-lisn-place: "top", "bottom", "left" or "right"
  • data-lisn-draggable: "true" or "false"
  • data-lisn-clickable: "true" or "false"

To use with auto-widgets (HTML API) (see settings.autoWidgets), the following CSS classes or data attributes are recognized:

  • lisn-scrollbar class or data-lisn-scrollbar attribute set on the scrollable element that you want to enable custom scrollbars for

See below examples for what values you can use set for the data attribute in order to modify the configuration of the automatically created widget.

Example

This will create custom scrollbars for the main scrolling element (see settings.mainScrollableElementSelector).

This will work even if settings.autoWidgets) is false

<!-- LISN should be loaded beforehand -->
<script>
  // You can also just customise global default settings:
  // LISN.settings.scrollbarPositionV = "top";
  // LISN.settings.scrollbarAutoHide = 3000;
  // LISN.settings.scrollbarUseHandle = true;

  LISN.widgets.Scrollbar.enableMain({
    position: "top",
    autoHide: 3000,
    useHandle: true
  });
</script>

Example

This will create custom scrollbars for a custom scrolling element (i.e. one with overflow "auto" or "scroll").

<div class="scrolling lisn-scrollbar">
  <!-- content here... -->
</div>

Example

As above but with custom settings.

<div
  class="scrolling"
  data-lisn-scrollbar="hide-native=false
                       | positionH=top
                       | positionV=left
                       | auto-hide=2000
                       | click-scroll=false
                       | drag-scroll=false
                       | use-handle=false
                       ">
  <!-- content here... -->
</div>

Hierarchy (View Summary)

Methods

enableMain get register

Constructors

constructor

Properties

destroy disable enable getElement getScrollable isDestroyed isDisabled onDestroy onDisable onEnable toggleEnable

Methods

StaticenableMain

Staticget

Staticregister

Constructors

constructor

Properties

Readonlydestroy

destroy: () => Promise<void>

Undoes all modifications to the element and returns it to its original state.

You will need to recreate it if you want to enable its functionality again.

Readonlydisable

disable: () => Promise<void>

Disables the functionality of the widget. What this means is specific to each widget.

Readonlyenable

enable: () => Promise<void>

Re-enables the functionality of the widget. What this means is specific to each widget.

ReadonlygetElement

getElement: () => Element

Returns the element passed to the widget constructor.

ReadonlygetScrollable

getScrollable: () => Element

Returns the actual scrollable element created by us which will be a descendant of the original element passed to the constructor (unless settings.contentWrappingAllowed is false).

ReadonlyisDestroyed

isDestroyed: () => boolean

Returns true if the widget is destroyed.

ReadonlyisDisabled

isDisabled: () => boolean

Returns true if the widget is currently disabled.

ReadonlyonDestroy

onDestroy: (handler: WidgetHandler) => void

The given handler will be called when the widget is destroyed.

ReadonlyonDisable

onDisable: (handler: WidgetHandler) => void

The given handler will be called when the widget is disabled.

ReadonlyonEnable

onEnable: (handler: WidgetHandler) => void

The given handler will be called when the widget is enabled.

ReadonlytoggleEnable

toggleEnable: () => Promise<void>

Re-enables the widget if disabled, otherwise disables it.

Settings

Member Visibility

On This Page

Methods
Constructors
Properties