Variable settings`Const` `Readonly`

settings: {
    aspectRatioBreakpoints: {
        square: number;
        tall: number;
        "very-tall": number;
        "very-wide": number;
        wide: number;
    };
    autoWidgets: boolean;
    contentWrappingAllowed: boolean;
    darkThemeClassName: string;
    deltaLineHeight: number;
    deltaPageHeight: number;
    deltaPageWidth: number;
    deviceBreakpoints: {
        desktop: number;
        mobile: number;
        "mobile-wide": number;
        tablet: number;
    };
    lightThemeClassName: string;
    mainScrollableElementSelector: null
    | string;
    pageLoadTimeout: number;
    remoteLoggerOnMobileOnly: boolean;
    remoteLoggerURL: null | string;
    sameHeightDebounceWindow: number;
    sameHeightDiffTolerance: number;
    sameHeightMaxFreeR: number;
    sameHeightMaxWidthR: number;
    sameHeightMinGap: number;
    sameHeightResizeThreshold: number;
    scrollbarAutoHide: number;
    scrollbarClickScroll: boolean;
    scrollbarDragScroll: boolean;
    scrollbarHideNative: boolean;
    scrollbarOnMobile: boolean;
    scrollbarPositionH: string;
    scrollbarPositionV: string;
    scrollbarUseHandle: boolean;
    verbosityLevel: number;
} = ...

LISN's settings.

If you wish to modify them, then you need to do so immediately after loading LISN before you instantiate any watchers, etc. For example:

<!doctype html>
<html>
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width" />
    <script src="lisn.js" charset="utf-8"></script>
    <script charset="utf-8">
      // modify LISN settings, for example:
      LISN.settings.deviceBreakpoints.desktop = 1024;
    </script>
  </head>
  <body>
  </body>
</html>

Type declaration

aspectRatioBreakpoints: {
    square: number;
    tall: number;
    "very-tall": number;
    "very-wide": number;
    wide: number;
}
Set custom aspect ratio breakpoints (as ratio of width to height).

The value of each sets its lower limit, i.e. it specifies an aspect ratio that is wider than the given value (and up to the next wider one).

If you specify only some of the below aspect ratios, then the other ones will keep their default breakpoint values.

Adding aspect ratio types, other than the ones listed below is not supported.
- square: number
  Anything with a wider aspect ratio than the given value is "square", up to the value of "wide".
  Default Value
```
3 / 4
```
- tall: number
  Anything with a wider aspect ratio than the given value is "tall", up to the value of "square".
  Default Value
```
9 / 16
```
- very-tall: number
  This should be left as 0 as it's the catch-all for anything with a narrower aspect ratio than "tall".
  Default Value
```
0
```
- very-wide: number
  Anything with a wider aspect ratio than the given value is "very-wide".
  Default Value
```
16 / 9
```
- wide: number
  Anything with a wider aspect ratio than the given value is "wide", up to the value of "very-wide".
  Default Value
```
4 / 3
```
autoWidgets: boolean
This enables LISN's HTML API. Then the page will be parsed (and watched for dynamically added elements at any time) for any elements matching a widget selector. Any element that has a matching CSS class or data attribute will be setup according to the relevant widget, which may wrap, clone or add attributes to the element.

This is enabled by default for bundles, and disabled otherwise.

IMPORTANT: You must set this before the document readyState becomes interactive.

Default Value
false in general, but true in browser bundles
contentWrappingAllowed: boolean
This setting allows us to automatically wrap certain elements or groups of elements into a single div or span element to allow for more reliable or efficient working of certain features. In particular:
1. View tracking using relative offsets and a scrolling root requires wrapping
When using view position tracking with a percentage offset specification (e.g. top: 50%) and a custom root element that is scrollable_ (and obviously has a size smaller than the content), you MUST enable content wrapping, otherwise the trigger offset elements cannot be positioned relative to the scrolling content size.
1. Scroll tracking
When using scroll tracking, including scrollbars, on a scrolling element (that obviously has a size smaller than the content), it's recommended for the content of the scrollable element to be wrapped in a single div container, to allow for more efficient and reliable detection of changes in the scrollable content size.

If content wrapping is disabled, when scroll tracking is used on a given element (other than the root of the document), each of the immediate children of the scrollable element have their sizes tracked, which could lead to more resource usage.
1. Scrollbars on custom elements
When you setup a Widgets.Scrollbar widget for a custom scrollable element that may not be the main scrollable (and therefore won't take up the full viewport all the time), then to be able to position to scrollbar relative to the scrollable element, its content needs to be wrapped.

If this setting is OFF, then the scrollbars on custom elements have to rely on position sticky which doesn't have as wide browser support as the default option.
1. Animating on viewport enter/leave
For elements that have transforms applied as part of an animation or transition, if you wish to run or reverse the animation when the element enters or leaves the viewport, then the transform can interfere with the viewport tracking. For example, if undoing the animation as soon as the element leaves the viewport makes it enter it again (because it's moved), then this will result in a glitch.

If content wrapping is disabled, then to get around such issues, a dummy element is positioned on top of the actual element and is the one tracked across the viewport instead. Either approach could cause issues depending on your CSS, so it's your choice which one is applied.

If you can, it's recommended to leave this setting ON. You can still disable wrapping on a per-element basis by setting data-lisn-no-wrap attribute on it.
Default Value
```
true
```
darkThemeClassName: string
The CSS class that enables dark theme.

IMPORTANT: If you change this, you should also change the $dark-theme-cls variable in the SCSS configuration, or otherwise add the following to your CSS:

.custom-dark-theme-cls { --lisn-color-fg: some-light-color; --lisn-color-fg-t: some-light-color-with-transparency; --lisn-color-bg: some-dark-color; --lisn-color-bg-t: some-dark-color-with-transparency; }
deltaLineHeight: number
Used to determine the effective delta in pixels for gestures triggered by some key (arrows) and wheel events (where the browser reports the delta mode to be LINE).

Value is in pixels.
Default Value
```
40
```
deltaPageHeight: number
Used to determine the effective delta in pixels for gestures triggered by some key (PageUp/PageDown/Space) and wheel events (where the browser reports the delta mode to be PAGE).

Value is in pixels.
Default Value
```
800
```
deltaPageWidth: number
Used to determine the effective delta in pixels for gestures triggered by some wheel events (where the browser reports the delta mode to be PAGE).

Value is in pixels.
Default Value
```
1600
```
deviceBreakpoints: { desktop: number; mobile: number; "mobile-wide": number; tablet: number }
Set custom device breakpoints as width in pixels.

The value of each sets its lower limit, i.e. it specifies a device whose width is larger than the given value (and up to the next larger one).

If you specify only some of the below devices, then the other ones will keep their default breakpoint values.

Adding device types, other than the ones listed below is not supported.
- desktop: number
  Anything wider than the given value is "desktop".
  Default Value
```
992
```
- mobile: number
  This should be left as 0 as it's the catch-all for anything narrower than "mobile-wide".
  Default Value
```
0
```
- mobile-wide: number
  Anything wider than the given value is "mobile-wide", up to the value of "tablet".
  Default Value
```
576
```
- tablet: number
  Anything wider than the given value is "tablet", up to the value of "desktop".
  Default Value
```
768
```
lightThemeClassName: string
The CSS class that enables light theme.

IMPORTANT: If you change this, you should also change the $light-theme-cls variable in the SCSS configuration, or otherwise add the following to your CSS:

:root, .custom-light-theme-cls { --lisn-color-fg: some-dark-color; --lisn-color-fg-t: some-dark-color-with-transparency; --lisn-color-bg: some-light-color; --lisn-color-bg-t: some-light-color-with-transparency; }
mainScrollableElementSelector: null | string
A unique selector (preferably #some-id) for the element that holds the main page content, if other than document.body.

E.g. if your main content is inside a custom scrollable container, rather than directly in document.body, then pass a selector for it here.

The element must be scrollable, i.e. have a fixed size and overflow: scroll.

IMPORTANT: You must set this before initializing any watchers, widgets, etc. If you are using the HTML API, then you must set this before the document readyState becomes interactive.
Default Value
```
null
```
pageLoadTimeout: number
The timeout in milliseconds for waiting for the document.readyState to become complete. The timer begins once the readyState becomes interactive.

The page will be considered "ready" either when the readyState becomes complete or this many milliseconds after it becomes interactive, whichever is first.

Set to 0 or a negative number to disable timeout.
Default Value
```
2000 // i.e. 2s
```
remoteLoggerOnMobileOnly: boolean
Enable remote logging only on mobile devices.

You can always disable remote logging for any page by setting disableRemoteLog=1 URL query parameter.

Note: Logging is not available in bundles (except in the debug bundle).
Default Value
```
false
```
remoteLoggerURL: null | string
The URL of the remote logger to connect to. LISN uses socket.io-client to talk to the client and emits messages on the following namespaces:
- console.debug
- console.log
- console.info
- console.warn
- console.error
There is a simple logging server that ships with LISN, see the source code repository.

You can always explicitly disable remote logging on a given page by setting disableRemoteLog=1 query parameter in the URL.

Note: Logging is not available in bundles (except in the debug bundle).
Default Value
```
null
```
sameHeightDebounceWindow: number
Default setting for SameHeightConfig.debounceWindow.
Default Value
```
100
```
sameHeightDiffTolerance: number
Default setting for SameHeightConfig.diffTolerance.
Default Value
```
15
```
sameHeightMaxFreeR: number
Default setting for SameHeightConfig.maxFreeR.
Default Value
```
0.4
```
sameHeightMaxWidthR: number
Default setting for SameHeightConfig.maxWidthR.
Default Value
```
1.7
```
sameHeightMinGap: number
Default setting for SameHeightConfig.minGap.
Default Value
```
30
```
sameHeightResizeThreshold: number
Default setting for SameHeightConfig.resizeThreshold.
Default Value
```
5
```
scrollbarAutoHide: number
Default setting for ScrollbarConfig.autoHide.
Default Value
```
-1
```
scrollbarClickScroll: boolean
Default setting for ScrollbarConfig.clickScroll.
Default Value
```
true
```
scrollbarDragScroll: boolean
Default setting for ScrollbarConfig.dragScroll.
Default Value
```
true
```
scrollbarHideNative: boolean
Default setting for ScrollbarConfig.hideNative.
Default Value
```
true
```
scrollbarOnMobile: boolean
Default setting for ScrollbarConfig.onMobile.
Default Value
```
false
```
scrollbarPositionH: string
Default setting for ScrollbarConfig.positionH.
Default Value
```
"bottom"
```
scrollbarPositionV: string
Default setting for ScrollbarConfig.positionV.
Default Value
```
"right"
```
scrollbarUseHandle: boolean
Default setting for ScrollbarConfig.useHandle.
Default Value
```
false
```
verbosityLevel: number
Controls the debugging verbosity level. Values from 0 (none) to 10 (insane) are recognized.

Note: Logging is not available in bundles except in the "debug" bundle.

Default Value
0 except in the "debug" bundle where it defaults to 10

Variable settingsConst Readonly

Type declaration

aspectRatioBreakpoints: { square: number; tall: number; "very-tall": number; "very-wide": number; wide: number;}

square: number

Default Value

tall: number

Default Value

very-tall: number

Default Value

very-wide: number

Default Value

wide: number

Default Value

autoWidgets: boolean

Default Value

contentWrappingAllowed: boolean

Default Value

darkThemeClassName: string

deltaLineHeight: number

Default Value

deltaPageHeight: number

Default Value

deltaPageWidth: number

Default Value

deviceBreakpoints: { desktop: number; mobile: number; "mobile-wide": number; tablet: number }

desktop: number

Default Value

mobile: number

Default Value

mobile-wide: number

Default Value

tablet: number

Default Value

lightThemeClassName: string

mainScrollableElementSelector: null | string

Default Value

pageLoadTimeout: number

Default Value

remoteLoggerOnMobileOnly: boolean

Default Value

remoteLoggerURL: null | string

Default Value

sameHeightDebounceWindow: number

Default Value

sameHeightDiffTolerance: number

Default Value

sameHeightMaxFreeR: number

Default Value

sameHeightMaxWidthR: number

Default Value

sameHeightMinGap: number

Default Value

sameHeightResizeThreshold: number

Default Value

scrollbarAutoHide: number

Default Value

scrollbarClickScroll: boolean

Default Value

scrollbarDragScroll: boolean

Default Value

scrollbarHideNative: boolean

Default Value

scrollbarOnMobile: boolean

Default Value

scrollbarPositionH: string

Default Value

scrollbarPositionV: string

Default Value

scrollbarUseHandle: boolean

Default Value

verbosityLevel: number

Default Value

Settings

Variable settings`Const` `Readonly`

aspectRatioBreakpoints: {
square: number;
tall: number;
"very-tall": number;
"very-wide": number;
wide: number;
}