# utils/dom/scroll

module

<a id="type-definitions">

## Type Definitions

<a id="typedef-IfTrue">

### `IfTrue`

<a id="functions">

## Functions

<a id="function-scrollAncestorsToShowTarget">

### `scrollAncestorsToShowTarget( target, ancestorOffset?, limiterElement?, alignToTop?, forceScroll? ) → void`

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

**Note**: The ancestor walk crosses shadow DOM boundaries, continuing from the host element of a shadow root instead of stopping at it, so scrollable ancestors in the surrounding document are scrolled too. Works for open and closed shadow roots alike.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/dom/scroll.ts#L191)

#### 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.

* `alignToTop?: boolean`

  When set `true`, the function will make sure the `target` is scrolled up to the top boundary of the 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 target elements that must be scrolled down because they will appear at the top of the boundary anyway.

* `forceScroll?: true`

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

#### Returns

* `void`

<a id="function-scrollViewportToShowTarget">

### `scrollViewportToShowTarget( options = { options.alignToTop?, options.ancestorOffset?, options.forceScroll?, options.target, options.viewportOffset? } ) → 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.

**Note**: The ancestor walk crosses shadow DOM boundaries, continuing from the host element of a shadow root instead of stopping at it, so scrollable ancestors in the surrounding document are scrolled too. Works for open and closed shadow roots alike.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/dom/scroll.ts#L66)

#### 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 ]
    ```

  * `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`

---

Full index of the CKEditor 5 API reference: [llms.txt](llms.txt)