Class ScrollPositionSource

Scroll-based position source.

Maps scroll position to a timeline position. The position is calculated as a percentage of the scroll progress multiplied by the configured duration.

Implements IPositionSource and ISeekable.

Example

const source = new ScrollPositionSource({
  selector: '#scroll-container',
  duration: 100, // 100 seconds timeline
});

await source.init();

source.onPosition((position) => {
  console.log(`Scroll at ${position}s of 100s`);
});

source.onBoundaryReached((boundary) => {
  if (boundary === 'end') {
    console.log('Scrolled to bottom');
  }
});

await source.activate();

Hierarchy (View Summary)

BasePositionSource
- ScrollPositionSource

Implements

ISeekable

Index

Constructors

constructor

new ScrollPositionSource(
config: ScrollPositionSourceConfig,
): ScrollPositionSource
Create a new scroll-based position source.
Parameters
- config: ScrollPositionSourceConfig
  Configuration options
Returns ScrollPositionSource
Overrides BasePositionSource.constructor
- Defined in timelineproviders/position-sources/scroll-position-source.ts:74

Accessors

loop

get loop(): boolean
Whether to loop when reaching the end boundary.

When true, the source resets to position 0 and continues. When false, the source emits 'end' boundary and deactivates.

For sources where looping is not applicable (e.g., mouse position), this property has no effect.

Returns boolean
Inherited from BasePositionSource.loop
- Defined in timelineproviders/position-sources/base-position-source.ts:81
set loop(value: boolean): void
Whether to loop when reaching the end boundary.

When true, the source resets to position 0 and continues. When false, the source emits 'end' boundary and deactivates.

For sources where looping is not applicable (e.g., mouse position), this property has no effect.
Parameters
- value: boolean
Returns void
Inherited from BasePositionSource.loop
- Defined in timelineproviders/position-sources/base-position-source.ts:85

state

get state(): TSourceState
Current state of the position source

Returns TSourceState
Inherited from BasePositionSource.state
- Defined in timelineproviders/position-sources/base-position-source.ts:77

Methods

activate

activate(): Promise<void>
Activate the position source to begin emitting position updates.

Transitions state from inactive or suspended to active.

Returns Promise<void>
Throws
If activation fails (e.g., autoplay blocked, permission denied)
Inherited from BasePositionSource.activate
- Defined in timelineproviders/position-sources/base-position-source.ts:110

deactivate

deactivate(): void
Deactivate the position source and reset to initial state.

Transitions state to inactive. Position is reset (typically to 0).

Returns void
Inherited from BasePositionSource.deactivate
- Defined in timelineproviders/position-sources/base-position-source.ts:136

destroy

destroy(): void
Destroy the position source and release all resources.

After calling destroy, the source cannot be reused. Removes event listeners, closes connections, clears timers.

Returns void
Inherited from BasePositionSource.destroy
- Defined in timelineproviders/position-sources/base-position-source.ts:97

`Protected`doDestroy

doDestroy(): void
Perform source-specific cleanup.

Called by destroy(). Override to release resources, unbind listeners, etc.

Returns void
Overrides BasePositionSource.doDestroy
- Defined in timelineproviders/position-sources/scroll-position-source.ts:97

`Protected`doInit

doInit(): Promise<void>
Perform source-specific initialization.

Called by init(). Override to load resources, bind listeners, etc.

Returns Promise<void>
Overrides BasePositionSource.doInit
- Defined in timelineproviders/position-sources/scroll-position-source.ts:83

`Protected`emitBoundary

emitBoundary(boundary: TBoundary): void
Emit a boundary event to all registered callbacks.
Parameters
- boundary: TBoundary
  The boundary type ('start' or 'end')
Returns void
Inherited from BasePositionSource.emitBoundary
- Defined in timelineproviders/position-sources/base-position-source.ts:203

getDuration

getDuration(): number
Get the total duration.

Returns number
Duration in seconds (or source-specific units), or Infinity for unbounded sources
Inherited from BasePositionSource.getDuration
- Defined in timelineproviders/position-sources/base-position-source.ts:158

getPosition

getPosition(): number
Get the current position.

Returns number
Current position in seconds (or source-specific units)
Inherited from BasePositionSource.getPosition
- Defined in timelineproviders/position-sources/base-position-source.ts:154

init

init(): Promise<void>
Initialize the position source.

Performs any async setup required before the source can be activated. For example: loading media, binding event listeners, establishing connections.

Returns Promise<void>
Throws
If initialization fails (e.g., media load error, connection refused)
Inherited from BasePositionSource.init
- Defined in timelineproviders/position-sources/base-position-source.ts:93

onActivated

onActivated(callback: () => void): void
Register a callback for when the source becomes active.

Called once each time the source transitions to the active state. This is equivalent to "first frame" semantics - for RAF sources it's the first tick, for video sources it's when playback actually starts.
Parameters
- callback: () => void
  Function called when source becomes active
Returns void
Inherited from BasePositionSource.onActivated
- Defined in timelineproviders/position-sources/base-position-source.ts:174

onBoundaryReached

onBoundaryReached(callback: (boundary: TBoundary) => void): void
Register a callback for boundary events.

Called when position reaches a boundary (start or end). For looping sources, 'end' is emitted before reset.
Parameters
- callback: (boundary: TBoundary) => void
  Function receiving the boundary type
Returns void
Inherited from BasePositionSource.onBoundaryReached
- Defined in timelineproviders/position-sources/base-position-source.ts:170

onPosition

onPosition(callback: (position: number) => void): void
Register a callback for position updates.

Called whenever the position changes while the source is active. Frequency depends on the source type (e.g., RAF tick, video timeupdate).
Parameters
- callback: (position: number) => void
  Function receiving the current position
Returns void
Inherited from BasePositionSource.onPosition
- Defined in timelineproviders/position-sources/base-position-source.ts:166

seek

seek(position: number): Promise<number>
Seek to a specific position by programmatically scrolling.
Parameters
- position: number
  Target position in seconds (0 to duration)
Returns Promise<number>
Actual position after scroll
Implementation of ISeekable.seek
- Defined in timelineproviders/position-sources/scroll-position-source.ts:137

`Protected`setPosition

setPosition(position: number): void
Set the current position and emit to callbacks.

Only emits if the source is active.
Parameters
- position: number
  New position value
Returns void
Inherited from BasePositionSource.setPosition
- Defined in timelineproviders/position-sources/base-position-source.ts:189

`Protected`startTicking

startTicking(): void
Start emitting position updates.

Called when transitioning to active state. Override to start timers, begin listening to events, etc.

Returns void
Overrides BasePositionSource.startTicking
- Defined in timelineproviders/position-sources/scroll-position-source.ts:107

`Protected`stopTicking

stopTicking(): void
Stop emitting position updates.

Called when transitioning from active to suspended or inactive. Override to stop timers, pause listening, etc.

Returns void
Overrides BasePositionSource.stopTicking
- Defined in timelineproviders/position-sources/scroll-position-source.ts:118

suspend

suspend(): void
Suspend the position source, preserving current position.

Transitions state from active to suspended. Position updates stop but position is preserved for later resumption.

Returns void
Inherited from BasePositionSource.suspend
- Defined in timelineproviders/position-sources/base-position-source.ts:125

Class ScrollPositionSource

Example

Hierarchy (View Summary)

Implements

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns ScrollPositionSource

Accessors

loop

Returns boolean

Parameters

Returns void

state

Returns TSourceState

Methods

activate

Returns Promise<void>

Throws

deactivate

Returns void

destroy

Returns void

ProtecteddoDestroy

Returns void

ProtecteddoInit

Returns Promise<void>

ProtectedemitBoundary

Parameters

Returns void

getDuration

Returns number

getPosition

Returns number

init

Returns Promise<void>

Throws

onActivated

Parameters

Returns void

onBoundaryReached

Parameters

Returns void

onPosition

Parameters

Returns void

seek

Parameters

Returns Promise<number>

ProtectedsetPosition

Parameters

Returns void

ProtectedstartTicking

Returns void

ProtectedstopTicking

Returns void

suspend

Returns void

Settings

On This Page

`Protected`doDestroy

`Protected`doInit

`Protected`emitBoundary

`Protected`setPosition

`Protected`startTicking

`Protected`stopTicking