LineObserver

A performant scroll interaction observer that triggers handlers when elements cross a configurable "trigger line" in the viewport.

• Single shared requestAnimationFrame loop (only runs when instances are active)
• Batched DOM read/write operations via IntersectionObserver + RAF
• Configurable trigger line per instance (px, %, vh, vw)
• Bidirectional scroll support with consistent offset values
• Sets a --scroll-offset CSS custom property on active elements by default

Installation

npm

npm install @happyprime/line-observer

import LineObserver from '@happyprime/line-observer';

Script tag

<script src="path/to/line-observer.js" type="module"></script>
<script>
  const observer = new LineObserver();
</script>

When loaded via script tag, LineObserver is available as window.LineObserver.

Quick start

const observer = new LineObserver({ triggerLine: '50vh' });

document.querySelectorAll('.observed').forEach((el) => {
  observer.register(el, {
    activeClass: 'is-active',
    onActivate: (element) => console.log('Activated', element),
    onDeactivate: (element) => console.log('Deactivated', element),
    onScroll: (offset, element, instance) => {
      const progress = offset / instance.elementHeight;
      element.style.opacity = Math.min(1, progress);
    },
  });
});

Constructor options

Options passed to the constructor set defaults for all registered elements. Each option can be overridden per element in register().

const observer = new LineObserver({
  triggerLine: '50vh',        // Position of the trigger line (default: '50vh')
  activeClass: 'is-active',  // Class added when element is active (default: 'is-active')
  activateFrom: 'both',      // Where activation triggers from: 'both', 'below', 'above' (default: 'both')
  nearMargin: 100,           // IO detection band half-width in px (default: 100)
  cssCustomProperty: true,   // Set --scroll-offset on active elements (default: true)
  onActivate: null,          // Callback when element becomes active (default: null)
  onDeactivate: null,        // Callback when element becomes inactive (default: null)
  onScroll: null,            // Callback each frame while element is active (default: null)
});

Option	Type	Default	Description
triggerLine	string | number	'50vh'	Where the trigger line sits in the viewport. Accepts px, %, vh, vw units or a raw number (treated as px).
activeClass	string	'is-active'	CSS class added to the element while it is in the active zone.
activateFrom	string	'both'	Which side the element crosses the trigger line from to activate: 'below' (scrolling down), 'above' (scrolling up), or 'both'.
nearMargin	number	100	Half-width (in px) of the IntersectionObserver detection band around the trigger line. Larger values detect elements earlier but keep the animation loop running longer. A safety net in the loop handles elements that skip the band during very fast scrolling.
cssCustomProperty	boolean	true	When true, sets --scroll-offset on active elements every frame. Set to false if you only use callbacks.
onActivate	function | null	null	Called when an element crosses the trigger line and becomes active. Receives (element, instance).
onDeactivate	function | null	null	Called when an element leaves the active zone. Receives (element, instance).
onScroll	function | null	null	Called every animation frame while the element is active. Receives (offset, element, instance).

Methods

register(element, options?)

Register an element for observation. Options override the constructor defaults for this element. Returns the LineObserver instance for chaining.

observer
  .register(el1, { triggerLine: '30vh' })
  .register(el2, { activateFrom: 'below' })
  .register(el3);

unregister(element)

Stop observing an element. Removes the active class and cleans up the --scroll-offset property. Returns the instance for chaining.

observer.unregister(el1);

destroy()

Tear down everything: stops the RAF loop, disconnects all IntersectionObservers, removes classes and custom properties from all elements, and removes the resize listener.

observer.destroy();

getActiveCount()

Returns the number of elements currently in the active zone.

observer.getActiveCount(); // 3

getTotalCount()

Returns the total number of registered elements.

observer.getTotalCount(); // 10

isActive()

Returns true if the internal RAF loop is currently running.

observer.isActive(); // true

getDirection()

Returns the current scroll direction: 'up' or 'down'.

observer.getDirection(); // 'down'

Instance data in callbacks

The instance object passed to onActivate, onDeactivate, and onScroll callbacks contains:

Property	Type	Description
element	HTMLElement	The observed DOM element.
options	object	Merged options (constructor defaults + per-element overrides).
state	string	Current state: 'inactive', 'active', or 'passed'.
activationScrollY	number	The window.scrollY value when the element was activated.
elementHeight	number	The element's offsetHeight, captured at activation.
triggerLinePx	number	The trigger line position in pixels (computed from the triggerLine option).

observer.register(el, {
  onScroll: (offset, element, instance) => {
    // offset = scrollY - activationScrollY (clamped to >= 0)
    const progress = offset / instance.elementHeight;
    element.style.setProperty('--progress', Math.min(1, progress));
  },
  onActivate: (element, instance) => {
    console.log('State:', instance.state);             // 'active'
    console.log('Trigger at:', instance.triggerLinePx); // e.g. 400
    console.log('Height:', instance.elementHeight);     // e.g. 800
  },
});

How the trigger line works

The trigger line is an invisible horizontal line across the viewport. An element becomes active when its top edge scrolls above the line and remains active until its bottom edge also scrolls above it.

Each registered element can be in one of three states:

• 'inactive' -- element is entirely below the trigger line.
• 'active' -- element spans the trigger line (top above, bottom below).
• 'passed' -- element is entirely above the trigger line.

Supported units

Value	Meaning
'50vh'	50% of viewport height (default -- middle of screen)
'100px'	100 pixels from top of viewport
'25%'	25% of viewport height (equivalent to '25vh')
'50vw'	50% of viewport width
200	Raw number, treated as 200px

// Trigger near the top of the viewport
new LineObserver({ triggerLine: '10vh' });

// Trigger at a fixed pixel position
new LineObserver({ triggerLine: '200px' });

// Override per element
observer.register(el, { triggerLine: '75vh' });

Activation filtering

The activateFrom option controls which direction the element must cross the trigger line from to activate.

// Only activate when element crosses trigger line from below
observer.register(el, { activateFrom: 'below' });

// Only activate when element crosses trigger line from above
observer.register(el, { activateFrom: 'above' });

// Activate from either direction (default)
observer.register(el, { activateFrom: 'both' });

When activateFrom is 'below':

• Elements activate only when they first touch the trigger line from below (user scrolling down).
• Elements will not activate when crossing from above.
• Once active, deactivation by scrolling back up (element returning below the trigger line) is suppressed.

When activateFrom is 'above':

• Elements activate only when they first touch the trigger line from above (user scrolling up).
• Elements will not activate when crossing from below.
• Once active, deactivation by scrolling back down (element passing above the trigger line) is suppressed.

The --scroll-offset CSS custom property

When cssCustomProperty is true (the default), LineObserver sets --scroll-offset on each active element every animation frame. The value is the number of pixels scrolled since the element was activated.

.observed {
  transform: translateY(calc(var(--scroll-offset, 0) * -0.5px));
}

.observed.is-active {
  opacity: calc(var(--scroll-offset, 0) / 500);
}

The property is reset to 0 when the element deactivates and removed entirely when the element is unregistered or the observer is destroyed.

To disable this behavior, set cssCustomProperty to false:

observer.register(el, {
  cssCustomProperty: false,
  onScroll: (offset) => {
    // handle offset in JS instead
  },
});

License

MIT License. See LICENSE for details.