Class ScrollProgress

Tracks scroll progress of a section relative to the viewport or a scroll root.

Emits update on scroll (and optionally only while the section is visible)
Exposes inProgress, outProgress, moveProgress, and progress
Supports a custom scroll container via root and optional useSvh height

Documentation

Hierarchy (View Summary)

Module<TC, TS, TM>
- ScrollProgress

Index

Constructors

constructor

new ScrollProgress(
    props?: TModuleProps<
        IScrollProgressCallbacksMap,
        IScrollProgressStaticProps,
        IScrollProgressMutableProps,
        ScrollProgress,
    >,
): ScrollProgress
Parameters
- Optionalprops: TModuleProps<
      IScrollProgressCallbacksMap,
      IScrollProgressStaticProps,
      IScrollProgressMutableProps,
      ScrollProgress,
  >
Returns ScrollProgress
Overrides Module.constructor
- Defined in src/components/ScrollProgress/index.ts:55

Accessors

callbacks

get callbacks(): Callbacks<CallbacksMap, this>
Retrieves the module's callbacks instance.

Returns Callbacks<CallbacksMap, this>
Inherited from Module.callbacks
- Defined in src/base/Module/index.ts:64

inProgress

get inProgress(): { x: number; y: number }
Progress while the section is entering the root.

Returns { x: number; y: number }
- Defined in src/components/ScrollProgress/index.ts:210

isDestroyed

get isDestroyed(): boolean
Indicates whether the instance has been destroyed.

After destruction, destroy is a no-op.

Returns boolean
Inherited from Module.isDestroyed
- Defined in src/internal/Destroyable/index.ts:24

isVisible

get isVisible(): boolean
Whether the section is currently considered visible (optimized mode).

Returns boolean
- Defined in src/components/ScrollProgress/index.ts:69

moveProgress

get moveProgress(): { x: number; y: number }
Progress while the section moves through the root (pin-like range).

Returns { x: number; y: number }
- Defined in src/components/ScrollProgress/index.ts:243

name

get name(): string
The name of the module, derived from the class name

Returns string
Inherited from Module.name
- Defined in src/base/Module/index.ts:57

outProgress

get outProgress(): { x: number; y: number }
Progress while the section is leaving the root.

Returns { x: number; y: number }
- Defined in src/components/ScrollProgress/index.ts:231

prefix

get prefix(): string
Optional prefix for classnames used by the module

Returns string
Inherited from Module.prefix
- Defined in src/base/Module/index.ts:52

progress

get progress(): { x: number; y: number }
Full travel progress from entering to fully leaving the root.

Returns { x: number; y: number }
- Defined in src/components/ScrollProgress/index.ts:270

props

get props(): TRequiredProps<MutableProps & StaticProps>
Current properties. Do not mutate these directly, use updateProps instead.

Returns TRequiredProps<MutableProps & StaticProps>
Inherited from Module.props
- Defined in src/base/Module/index.ts:47

rootBounds

get rootBounds(): IScrollProgressBounds
Root bounds used for progress math (viewport or root element).

Returns IScrollProgressBounds
- Defined in src/components/ScrollProgress/index.ts:74

section

get section(): Element
Section element whose progress is tracked.

Returns Element
- Defined in src/components/ScrollProgress/index.ts:64

sectionBounds

get sectionBounds(): IScrollProgressBounds
Section bounds relative to rootBounds.

Returns IScrollProgressBounds
- Defined in src/components/ScrollProgress/index.ts:79

Methods

`Protected`_addTempClassName

_addTempClassName(element: Element, ...classes: string[]): void
Adds prefixed classes to an element and removes them on destroy.

Skips classes that are already present on the element.
Parameters
- element: Element
  Target DOM element.
- ...classes: string[]
  Unprefixed class name segments.
Returns void
Inherited from Module._addTempClassName
- Defined in src/base/Module/index.ts:139

`Protected`_cn

_cn(...classes: string[]): string
Builds one or more prefixed class names.
Parameters
- ...classes: string[]
  Unprefixed class name segments.
Returns string
Space-separated prefixed class string.
Inherited from Module._cn
- Defined in src/base/Module/index.ts:127

`Protected`_destroy

_destroy(): void
Internal method to handle the destruction of the module. It removes all callbacks, destroys properties, and cleans up event listeners and class names.

Returns void
Inherited from Module._destroy
- Defined in src/base/Module/index.ts:202

`Protected`_emit

_emit<E extends keyof IScrollProgressCallbacksMap>(
event: E,
arg: IScrollProgressCallbacksMap[E],
): void
Emits a callback event with a fixed payload.
Type Parameters
- E extends keyof IScrollProgressCallbacksMap
Parameters
- event: E
- arg: IScrollProgressCallbacksMap[E]
Returns void
Inherited from Module._emit
- Defined in src/base/Module/index.ts:107

_getMutable

_getMutable(): { __mutableProp: true }
Set default mutable props

Returns { __mutableProp: true }
Overrides Module._getMutable
- Defined in src/components/ScrollProgress/index.ts:35

_getStatic

_getStatic(): {
    __staticProp: true;
    optimized: boolean;
    root: Element;
    section: Element;
    useSvh: boolean;
}
Get default static props

Returns {
    __staticProp: true;
    optimized: boolean;
    root: Element;
    section: Element;
    useSvh: boolean;
}
- __staticProp: true
- optimized: boolean
  If true, progress is calculated only while the section is within the viewport or the root element. Improves performance by avoiding unnecessary calculations.
  Default
  true
- root: Element
  The root element used as a reference for scroll progress calculation. Usually it is the scroll container. If null, the viewport is used as the reference.
  Default
  null
- section: Element
  The element whose scroll progress is tracked.
- useSvh: boolean
  If true, the scroll progress is calculated based on the small viewport height (svh in css) instead of the current viewport height (vh in css).
  Default
  false
Overrides Module._getStatic
- Defined in src/components/ScrollProgress/index.ts:31

`Protected`_handleProps

_handleProps(diff: Partial<IScrollProgressMutableProps>): void
Method that is called when the module's properties mutate. In most cases, used to handle callbacks.
Parameters
- diff: Partial<IScrollProgressMutableProps>
Returns void
Inherited from Module._handleProps
- Defined in src/base/Module/index.ts:117

destroy

destroy(): void
Destroys the instance and runs all registered cleanup actions.

Safe to call multiple times; subsequent calls are ignored.

Execution order:
1. _destroy
2. all onDestroy callbacks, in registration order
3. isDestroyed is set to true
Returns void
Inherited from Module.destroy
- Defined in src/internal/Destroyable/index.ts:46

getProgress

getProgress(
    topThreshold: number,
    rightThreshold: number,
    bottomThreshold: number,
    leftThreshold: number,
): { x: number; y: number }
Progress of the section's top/left corner between the given thresholds.
Parameters
- topThreshold: number
  Y start threshold.
- rightThreshold: number
  X end threshold.
- bottomThreshold: number
  Y end threshold.
- leftThreshold: number
  X start threshold.
Returns { x: number; y: number }
Progress along x and y.
Example
```
const progress = getProgress(0, vevet.width, vevet.height / 2, 0)
// progress.y is 0 at the start of the root, 1 at the vertical midpoint
```
- Defined in src/components/ScrollProgress/index.ts:187

on

on<T extends keyof IScrollProgressCallbacksMap>(
    target: T,
    listener: TCallbacksAction<IScrollProgressCallbacksMap[T], ScrollProgress>,
    settings?: ICallbacksSettings,
): () => void
Adds a custom callback to the module.
Type Parameters
- T extends keyof IScrollProgressCallbacksMap
Parameters
- target: T
  The event type to listen for (e.g., 'props', 'destroy').
- listener: TCallbacksAction<IScrollProgressCallbacksMap[T], ScrollProgress>
  The function to execute when the event is triggered.
- settings: ICallbacksSettings = {}
  Additional settings for the callback.
Returns () => void
Inherited from Module.on
- Defined in src/base/Module/index.ts:190

onDestroy

onDestroy(action: () => void): void
Registers a function to run when the instance is destroyed.

If the instance is already destroyed, action runs immediately.
Parameters
- action: () => void
  Cleanup function (for example remove listeners or DOM classes).
Returns void
Inherited from Module.onDestroy
- Defined in src/internal/Destroyable/index.ts:64

update

update(isForce?: boolean): void
Refreshes root/section bounds and emits update.
Parameters
- isForce: boolean = false
  When true, updates even if the section is not visible.
Returns void
- Defined in src/components/ScrollProgress/index.ts:142

updateProps

updateProps(props: Partial<IScrollProgressMutableProps>): void
Change module's mutable properties
Parameters
- props: Partial<IScrollProgressMutableProps>
Returns void
Inherited from Module.updateProps
- Defined in src/base/Module/index.ts:157

Class ScrollProgress

Hierarchy (View Summary)

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns ScrollProgress

Accessors

callbacks

Returns Callbacks<CallbacksMap, this>

inProgress

Returns { x: number; y: number }

isDestroyed

Returns boolean

isVisible

Returns boolean

moveProgress

Returns { x: number; y: number }

name

Returns string

outProgress

Returns { x: number; y: number }

prefix

Returns string

progress

Returns { x: number; y: number }

props

Returns TRequiredProps<MutableProps & StaticProps>

rootBounds

Returns IScrollProgressBounds

section

Returns Element

sectionBounds

Returns IScrollProgressBounds

Methods

Protected_addTempClassName

Parameters

Returns void

Protected_cn

Parameters

Returns string

Protected_destroy

Returns void

Protected_emit

Type Parameters

Parameters

Returns void

_getMutable

Returns { __mutableProp: true }

_getStatic

Returns { __staticProp: true; optimized: boolean; root: Element; section: Element; useSvh: boolean;}

__staticProp: true

optimized: boolean

Default

root: Element

Default

section: Element

useSvh: boolean

Default

Protected_handleProps

Parameters

Returns void

destroy

Returns void

getProgress

Parameters

Returns { x: number; y: number }

Example

on

Type Parameters

Parameters

Returns () => void

onDestroy

Parameters

Returns void

update

Parameters

`Protected`_addTempClassName

`Protected`_cn

`Protected`_destroy

`Protected`_emit

Returns {
__staticProp: true;
optimized: boolean;
root: Element;
section: Element;
useSvh: boolean;
}

`Protected`_handleProps