ScrollBar JAVASCRIPT UI Component API

ScrollBar Javascript API

Class

ScrollBar

ScrollBar

Scrollbar is a replacement of the default scroll bar with multiple UI Styling options.

Selector

smart-scroll-bar

Properties

AanimationSpecifies the current animation mode for the component. You can retrieve the current mode or assign a new one. Setting this property to 'none' disables all animations; other values will enable and determine the type of animation applied.
DdisabledDetermines whether the element is interactive or inactive. When enabled, users can interact with the element as intended. When disabled, the element becomes unresponsive to user input and typically appears visually distinct to indicate its inactive state.
LlargeStepDefines or retrieves the value of the scrollbar's large step increment. This large step value determines how much the scrollbar's position changes when the user clicks in the track area between the scrollbar's thumb (slider) and one of its arrow buttons. When the left mouse button is pressed in this area, the scrollbar advances or retreats by the specified large step amount, enabling quicker navigation through the content compared to single-step arrow button clicks.
UunlockKeyGets or sets the 'unlockKey' property, which is a unique key used to activate or unlock access to the product’s features or functionality.
LlocaleSpecifies or retrieves the current language setting. This property determines which language is used for displaying messages, working in conjunction with the messages property to select the appropriate set of localized text based on the specified language code (e.g., "en", "fr", "es").
LlocalizeFormatFunctionInvokes a callback function associated with the localization module, typically used to handle events or actions such as language changes, text translations, or updates to localized content within the application.
MmaxSpecifies or retrieves the maximum scrollable value of the scrollbar, determining the highest position to which the scrollbar thumb can be moved. This value defines the upper limit of the scrollable content range.
MmechanicalActionSpecifies or retrieves the type of mechanical action applied to the element. Mechanical action determines the exact moment when the element's value is updated—such as immediately upon interaction, after a confirmation (like releasing a button), or according to specific user actions. This property allows you to control how and when changes to the element’s value are registered and processed within the application.
MmessagesDefines an object containing string values that represent the various states of password strength (e.g., weak, medium, strong). Each key in the object corresponds to a specific strength level, allowing for customized messages or labels based on the user's password strength status.
MminDefines or retrieves the lowest possible value that the scrollbar can represent, determining the starting point of the scrollbar's range.
OorientationSpecifies or retrieves the orientation of the scrollbar, determining whether it is displayed horizontally or vertically.
RreadonlyIf the element has the readonly attribute, users will be able to see its value but will not be able to modify, edit, or otherwise interact with its contents through input actions. However, the element may still be focusable and its value can be changed programmatically using scripts.
RrightToLeftSets or retrieves a value that specifies whether the element's content alignment is optimized for languages that use right-to-left (RTL) scripts, such as Arabic or Hebrew. When enabled, the element's layout, text direction, and associated styles are adjusted to properly support RTL locales.
SshowButtonsControls the visibility of scrollbar buttons. When set, this property determines whether the scrollbar's increment and decrement buttons (commonly arrow buttons at the ends of the scrollbar) are shown or hidden. It can be used to either display or hide these buttons programmatically, and can also be queried to retrieve the current visibility state.
SstepDefines or retrieves the increment by which the scrollbar's value changes when a user clicks on the scrollbar's arrow (stepper) buttons. This value determines how much the scroll position increases or decreases with each button press, allowing for precise control over scrolling granularity.
TthemeSpecifies the theme to be applied to the element. The selected theme controls the visual appearance, including colors, typography, and overall styling, ensuring a consistent and cohesive look for the element within the user interface.
UunfocusableWhen set to true, this property prevents the element from receiving keyboard focus, making it unreachable via tab navigation or programmatically using focus methods.
VvalueSets a new value for the widget or retrieves its current value, depending on how the method is invoked. This allows you to programmatically update the widget's data or access its existing data as needed.

Events

CchangeThis event is triggered whenever the value of the associated element is modified by the user or programmatically. It occurs immediately after the value has changed, allowing you to perform custom actions in response to the update.

Methods

RrefreshRe-renders the element by updating its visual presentation on the screen, ensuring that any recent changes to its properties, styles, or content are accurately reflected in the user interface.

Properties

animation"none" | "simple" | "advanced"

Specifies the current animation mode for the component. You can retrieve the current mode or assign a new one. Setting this property to 'none' disables all animations; other values will enable and determine the type of animation applied.

Allowed Values

  • "none" - animation is disabled
  • "simple" - ripple animation is disabled
  • "advanced" - all animations are enabled

Default value

"advanced"

Example

Set the animation property. 

 <smart-scroll-bar animation='none'></smart-scroll-bar>

Set the animation property by using the HTML Element's instance. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 scrollbar.animation = 'simple';

Get the animation property. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 let animation = scrollbar.animation;

disabledboolean

Determines whether the element is interactive or inactive. When enabled, users can interact with the element as intended. When disabled, the element becomes unresponsive to user input and typically appears visually distinct to indicate its inactive state.

Default value

false

Example

Set the disabled property. 

 <smart-scroll-bar disabled></smart-scroll-bar>

Set the disabled property by using the HTML Element's instance. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 scrollbar.disabled = false;

Get the disabled property. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 let disabled = scrollbar.disabled;

largeStepinteger

Defines or retrieves the value of the scrollbar's large step increment. This large step value determines how much the scrollbar's position changes when the user clicks in the track area between the scrollbar's thumb (slider) and one of its arrow buttons. When the left mouse button is pressed in this area, the scrollbar advances or retreats by the specified large step amount, enabling quicker navigation through the content compared to single-step arrow button clicks.

Default value

100

Example

Set the largeStep property. 

 <smart-scroll-bar large-step='20'></smart-scroll-bar>

Set the largeStep property by using the HTML Element's instance. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 scrollbar.largeStep = 50;

Get the largeStep property. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 let largeStep = scrollbar.largeStep;

unlockKeystring

Gets or sets the 'unlockKey' property, which is a unique key used to activate or unlock access to the product’s features or functionality.

Default value

""

Example

Set the unlockKey property. 

 <smart-scroll-bar unlock-key=''></smart-scroll-bar>

Set the unlockKey property by using the HTML Element's instance. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 scrollbar.unlockKey = '1111-2222-3333-4444-5555';

Get the unlockKey property. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 let unlockKey = scrollbar.unlockKey;

localestring

Specifies or retrieves the current language setting. This property determines which language is used for displaying messages, working in conjunction with the messages property to select the appropriate set of localized text based on the specified language code (e.g., "en", "fr", "es").

Default value

"en"

Example

Set the locale property. 

 <smart-scroll-bar locale='de'></smart-scroll-bar>

Set the locale property by using the HTML Element's instance. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 scrollbar.locale = 'fr';

Get the locale property. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 let locale = scrollbar.locale;

localizeFormatFunctionfunction | null

Invokes a callback function associated with the localization module, typically used to handle events or actions such as language changes, text translations, or updates to localized content within the application.

Example

Set the localizeFormatFunction property. 

 <smart-scroll-bar localize-format-function='function(){return '...'}'></smart-scroll-bar>

Set the localizeFormatFunction property by using the HTML Element's instance. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 scrollbar.localizeFormatFunction = function(){return '...'};

Get the localizeFormatFunction property. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 let localizeFormatFunction = scrollbar.localizeFormatFunction;

maxinteger

Specifies or retrieves the maximum scrollable value of the scrollbar, determining the highest position to which the scrollbar thumb can be moved. This value defines the upper limit of the scrollable content range.

Default value

1000

Example

Set the max property. 

 <smart-scroll-bar max='200'></smart-scroll-bar>

Set the max property by using the HTML Element's instance. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 scrollbar.max = 500;

Get the max property. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 let max = scrollbar.max;

mechanicalAction"switchUntilReleased" | "switchWhenReleased" | "switchWhileDragging"

Specifies or retrieves the type of mechanical action applied to the element. Mechanical action determines the exact moment when the element's value is updated—such as immediately upon interaction, after a confirmation (like releasing a button), or according to specific user actions. This property allows you to control how and when changes to the element’s value are registered and processed within the application.

Default value

"switchWhileDragging"

Example

Set the mechanicalAction property. 

 <smart-scroll-bar mechanical-action='switchWhenReleased'></smart-scroll-bar>

Set the mechanicalAction property by using the HTML Element's instance. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 scrollbar.mechanicalAction = 'switchWhileDragging';

Get the mechanicalAction property. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 let mechanicalAction = scrollbar.mechanicalAction;

messagesobject

Defines an object containing string values that represent the various states of password strength (e.g., weak, medium, strong). Each key in the object corresponds to a specific strength level, allowing for customized messages or labels based on the user's password strength status.

Default value




"en": {

"propertyUnknownType": "'{{name}}' property is with undefined 'type' member!",

"propertyInvalidValue": "Invalid '{{name}}' property value! Actual value: {{actualValue}}, Expected value: {{value}}!",

"propertyInvalidValueType": "Invalid '{{name}}' property value type! Actual type: {{actualType}}, Expected type: {{type}}!",

"elementNotInDOM": "Element does not exist in DOM! Please, add the element to the DOM, before invoking a method.",

"moduleUndefined": "Module is undefined.",

"missingReference": "{{elementType}}: Missing reference to {{files}}.",

"htmlTemplateNotSuported": "{{elementType}}: Browser doesn't support HTMLTemplate elements.",

"invalidTemplate": "{{elementType}}: '{{property}}' property accepts a string that must match the id of an HTMLTemplate element from the DOM."

}

Example

Set the messages property. 

 <smart-scroll-bar messages='{"de":{"propertyUnknownType":"Die Eigenschaft '{{name}}' hat ein nicht definiertes 'type'-Member!","propertyInvalidValue":"Ungultiger Eigenschaftswert '{{name}}'! Aktueller Wert: {{actualValue}}, Erwarteter Wert: {{value}}!","propertyInvalidValueType":"Ungultiger Eigenschaftswert '{{name}}'! Aktueller Wert: {{actualType}}, Erwarteter Wert: {{type}}!","elementNotInDOM":"Element existiert nicht in DOM! Bitte fugen Sie das Element zum DOM hinzu, bevor Sie eine Methode aufrufen.","moduleUndefined":"Modul ist nicht definiert.","missingReference":"{{elementType}}: Fehlender Verweis auf {{files}}.","htmlTemplateNotSuported":"{{elementType}}: Browser unterstutzt keine HTMLTemplate-Elemente.","invalidTemplate":"{{elementType}}: '{{property}}' Die Eigenschaft akzeptiert eine Zeichenfolge, die mit der ID eines HTMLTemplate-Elements aus dem DOM ubereinstimmen muss."}}'></smart-scroll-bar>

Set the messages property by using the HTML Element's instance. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 scrollbar.messages = {"en":{"propertyUnknownType":"'{{name}}' property is with undefined 'type' member!","propertyInvalidValue":"Invalid '{{name}}' property value! Actual value: {{actualValue}}, Expected value: {{value}}!","propertyInvalidValueType":"Invalid '{{name}}' property value type! Actual type: {{actualType}}, Expected type: {{type}}!","elementNotInDOM":"Element does not exist in DOM! Please, add the element to the DOM, before invoking a method.","moduleUndefined":"Module is undefined.","missingReference":"{{elementType}}: Missing reference to {{files}}.","htmlTemplateNotSuported":"{{elementType}}: Browser doesn't support HTMLTemplate elements.","invalidTemplate":"{{elementType}}: '{{property}}' property accepts a string that must match the id of an HTMLTemplate element from the DOM."}};

Get the messages property. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 let messages = scrollbar.messages;

mininteger

Defines or retrieves the lowest possible value that the scrollbar can represent, determining the starting point of the scrollbar's range.

Default value

0

Example

Set the min property. 

 <smart-scroll-bar min='10'></smart-scroll-bar>

Set the min property by using the HTML Element's instance. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 scrollbar.min = 100;

Get the min property. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 let min = scrollbar.min;

orientation"horizontal" | "vertical"

Specifies or retrieves the orientation of the scrollbar, determining whether it is displayed horizontally or vertically.

Default value

"horizontal"

Example

Set the orientation property. 

 <smart-scroll-bar orientation='vertical'></smart-scroll-bar>

Set the orientation property by using the HTML Element's instance. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 scrollbar.orientation = 'horizontal';

Get the orientation property. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 let orientation = scrollbar.orientation;

readonlyboolean

If the element has the readonly attribute, users will be able to see its value but will not be able to modify, edit, or otherwise interact with its contents through input actions. However, the element may still be focusable and its value can be changed programmatically using scripts.

Default value

false

Example

Set the readonly property. 

 <smart-scroll-bar readonly></smart-scroll-bar>

Set the readonly property by using the HTML Element's instance. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 scrollbar.readonly = true;

Get the readonly property. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 let readonly = scrollbar.readonly;

rightToLeftboolean

Sets or retrieves a value that specifies whether the element's content alignment is optimized for languages that use right-to-left (RTL) scripts, such as Arabic or Hebrew. When enabled, the element's layout, text direction, and associated styles are adjusted to properly support RTL locales.

Default value

false
Try a demo showcasing the rightToLeft property.

Example

Set the rightToLeft property. 

 <smart-scroll-bar right-to-left></smart-scroll-bar>

Set the rightToLeft property by using the HTML Element's instance. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 scrollbar.rightToLeft = true;

Get the rightToLeft property. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 let rightToLeft = scrollbar.rightToLeft;

showButtonsboolean

Controls the visibility of scrollbar buttons. When set, this property determines whether the scrollbar's increment and decrement buttons (commonly arrow buttons at the ends of the scrollbar) are shown or hidden. It can be used to either display or hide these buttons programmatically, and can also be queried to retrieve the current visibility state.

Default value

true

Example

Set the showButtons property. 

 <smart-scroll-bar show-buttons></smart-scroll-bar>

Set the showButtons property by using the HTML Element's instance. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 scrollbar.showButtons = true;

Get the showButtons property. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 let showButtons = scrollbar.showButtons;

stepinteger

Defines or retrieves the increment by which the scrollbar's value changes when a user clicks on the scrollbar's arrow (stepper) buttons. This value determines how much the scroll position increases or decreases with each button press, allowing for precise control over scrolling granularity.

Default value

10

Example

Set the step property. 

 <smart-scroll-bar step='15'></smart-scroll-bar>

Set the step property by using the HTML Element's instance. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 scrollbar.step = 20;

Get the step property. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 let step = scrollbar.step;

themestring

Specifies the theme to be applied to the element. The selected theme controls the visual appearance, including colors, typography, and overall styling, ensuring a consistent and cohesive look for the element within the user interface.

Default value

""

Example

Set the theme property. 

 <smart-scroll-bar theme='blue'></smart-scroll-bar>

Set the theme property by using the HTML Element's instance. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 scrollbar.theme = 'red';

Get the theme property. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 let theme = scrollbar.theme;

unfocusableboolean

When set to true, this property prevents the element from receiving keyboard focus, making it unreachable via tab navigation or programmatically using focus methods.

Default value

false

Example

Set the unfocusable property. 

 <smart-scroll-bar unfocusable></smart-scroll-bar>

Set the unfocusable property by using the HTML Element's instance. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 scrollbar.unfocusable = false;

Get the unfocusable property. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 let unfocusable = scrollbar.unfocusable;

valuenumber

Sets a new value for the widget or retrieves its current value, depending on how the method is invoked. This allows you to programmatically update the widget's data or access its existing data as needed.

Default value

0

Example

Set the value property. 

 <smart-scroll-bar value='10'></smart-scroll-bar>

Set the value property by using the HTML Element's instance. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 scrollbar.value = 100;

Get the value property. 

 const scrollbar = document.querySelector('smart-scroll-bar');
 let value = scrollbar.value;

Events

changeCustomEvent

This event is triggered whenever the value of the associated element is modified by the user or programmatically. It occurs immediately after the value has changed, allowing you to perform custom actions in response to the update.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onChange

Arguments

evCustomEvent
ev.detailObject
ev.detail.value - A numeric value indicating the scroll position.
ev.detail.oldValue - A numeric value indicating the previous scroll position.
ev.detail.min - A numeric value indicating the min scroll position.
ev.detail.max - A numeric value indicating the max scroll position.

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Example

Set up the event handler of change event. 

const scrollbar = document.querySelector('smart-scroll-bar');
scrollbar.addEventListener('change', function (event) {
    const detail = event.detail,
        value = detail.value,
        oldValue = detail.oldValue,
        min = detail.min,
        max = detail.max;

	// event handling code goes here.
})

Methods

refresh(): void

Re-renders the element by updating its visual presentation on the screen, ensuring that any recent changes to its properties, styles, or content are accurately reflected in the user interface.


Invoke the refresh method.

const scrollbar = document.querySelector('smart-scroll-bar');
scrollbar.refresh();

CSS Variables

--smart-scroll-button-sizevar()

Default value

"16px"

smartScrollBar buttons size. Horizontal ScrollBar button width = Vertical ScrollBar button height. ScrollBar track is calculated defaultd on this value.

--smart-scroll-bar-sizevar()

Default value

"18px"

Default scrollbar size

--smart-scroll-bar-default-widthvar()

Default value

"var(--smart-editor-width)"

ScrollBar's default width.

--smart-scroll-bar-default-heightvar()

Default value

"var(--smart-scroll-bar-size)"

ScrollBar's default height.

--smart-scroll-bar-backgroundvar()

Default value

"#F1F1F1"

Default ScrollBar's background color.

--smart-scroll-bar-bordervar()

Default value

"#F1F1F1"

The border color of the ScrollBar

--smart-scroll-bar-thumb-border-top-right-radiusvar()

Default value

"0px"

Default ScrollBar's top-right border radius.

--smart-scroll-bar-thumb-border-top-left-radiusvar()

Default value

"0px"

Default ScrollBar's top-left border radius.

--smart-scroll-bar-thumb-border-bottom-left-radiusvar()

Default value

"0px"

Default ScrollBar's bottom-left border radius.

--smart-scroll-bar-thumb-border-bottom-right-radiusvar()

Default value

"0px"

Default ScrollBar's bottom-right border radius.

--smart-scroll-bar-thumb-backgroundvar()

Default value

"#C1C1C1"

The color of the ScrollBar's thumb.

--smart-scroll-bar-thumb-bordervar()

Default value

"#C1C1C1"

The color of the ScrollBar's thumb border.

--smart-scroll-bar-thumb-background-hovervar()

Default value

"#A8A8A8"

The background color of the ScrollBar's thumb in hover state.

--smart-scroll-bar-thumb-border-hovervar()

Default value

"#A8A8A8"

The border color of the ScrollBar's thumb in hover state.

--smart-scroll-bar-thumb-background-activevar()

Default value

"#787878"

The background color of the ScrollBar's thumb in active state.

--smart-scroll-bar-thumb-border-activevar()

Default value

"#787878"

The border color of the ScrollBar's thumb in active state.

--smart-scroll-bar-button-backgroundvar()

Default value

"#F1F1F1"

The background color of ScrollBar's navigation buttons.

--smart-scroll-bar-button-bordervar()

Default value

"#F1F1F1"

The border color of ScrollBar's navigation buttons.

--smart-scroll-bar-button-colorvar()

Default value

"#505050"

The color of ScrollBar's navigation buttons.

--smart-scroll-bar-button-background-hovervar()

Default value

"#D2D2D2"

The background color of the hovered ScrollBar's buttons.

--smart-scroll-bar-button-border-hovervar()

Default value

"#F1F1F1"

The border color of the hovered ScrollBar's buttons.

--smart-scroll-bar-button-color-hovervar()

Default value

"#505050"

The color of the hovered ScrollBar's buttons.

--smart-scroll-bar-button-background-activevar()

Default value

"#787878"

The background color of the ScrollBar's buttons in active state.

--smart-scroll-bar-button-border-activevar()

Default value

"#F1F1F1"

The border color of the ScrollBar's buttons in active state.

--smart-scroll-bar-button-color-activevar()

Default value

"#fff"

The color of the ScrollBar's buttons in active state.