utils/dom/scroll

Makes any page HTMLElement or Range (target) visible within its scrollable ancestors, e.g. if they have overflow: scroll CSS style.

Parameters

target : HTMLElement | Range

A target, which supposed to become visible to the user.

[ ancestorOffset ] : number

An offset between the target and the boundary of scrollable ancestors to be maintained while scrolling.

[ limiterElement ] : HTMLElement

The outermost ancestor that should be scrolled. If specified, it can prevent scrolling the whole page.

Returns

void

Makes any page HTMLElement or Range (target) visible inside the browser viewport. This helper will scroll all target ancestors and the web browser viewport to reveal the target to the user. If the target is already visible, nothing will happen.

Type parameters

T : extends boolean

U : extends true

Parameters

options : object

Additional configuration of the scrolling behavior.

Properties

[ options.alignToTop ] : T

When set true, the helper will make sure the target is scrolled up to the top boundary of the viewport and/or scrollable ancestors if scrolled up. When not set (default), the target will be revealed by scrolling as little as possible. This option will not affect targets that must be scrolled down because they will appear at the top of the boundary anyway.

                                            scrollViewportToShowTarget() with            scrollViewportToShowTarget() with
         Initial state                        alignToTop unset (default)                        alignToTop = true

┌────────────────────────────────┬─┐       ┌────────────────────────────────┬─┐        ┌────────────────────────────────┬─┐
│                                │▲│       │                                │▲│        │   [ Target to be revealed ]    │▲│
│                                │ │       │                                │ │        │                                │ │
│                                │█│       │                                │ │        │                                │ │
│                                │█│       │                                │ │        │                                │ │
│                                │ │       │                                │█│        │                                │ │
│                                │ │       │                                │█│        │                                │█│
│                                │ │       │                                │ │        │                                │█│
│                                │▼│       │   [ Target to be revealed ]    │▼│        │                                │▼│
└────────────────────────────────┴─┘       └────────────────────────────────┴─┘        └────────────────────────────────┴─┘


    [ Target to be revealed ]

Copy code

[ options.ancestorOffset ] : number

An offset from the boundary of scrollable ancestors (if any) the target will be moved by if the viewport is scrolled. It enhances the user experience by keeping the target some distance from the edge of the ancestors and thus making it easier to read or edit by the user.

Defaults to 0

[ options.forceScroll ] : U

When set true, the target will be aligned to the top of the viewport and scrollable ancestors whether it is already visible or not. This option will only work when alignToTop is true

options.target : HTMLElement | Range

A target, which supposed to become visible to the user.

[ options.viewportOffset ] : number | object

An offset from the edge of the viewport (in pixels) the target will be moved by if the viewport is scrolled. It enhances the user experience by keeping the target some distance from the edge of the viewport and thus making it easier to read or edit by the user.

Defaults to 0

Returns

void