Skip to main content

utils

uid

Generates a unique ID with an optional prefix.

This function returns a string that combines a prefix (default is 'id') with a unique incrementing number. It ensures each call will return a unique identifier.

uid(); // => 'id_1'
uid('test'); // => 'test_2'
uid(0); // => '0_3'

clamp

Restricts a value to lie within a specified range.

Ensures that value is no less than min and no greater than max.

clamp(1.5, 0.1, 0.9); // 0.9
clamp(0.001, 0.1, 0.9); // 0.1
clamp(0.5, 0, 1); // 0.5

scoped

Calculate the relative progress of a value within a given range (scope).

This function determines how far a value is within the specified range [min, max], returning a normalized value between 0 and 1. If the value is outside the range, the result can exceed 0 or 1 unless clamped separately.

scoped(0.35, 0, 1);
// => 0.35 // Progress of 0.35 within the range [0, 1]

scoped(0.35, 0.25, 1);
// => 0.133 // Progress of 0.35 within the range [0.25, 1]

scoped(0.35, 0.25, 0.9);
// => 0.153 // Progress of 0.35 within the range [0.25, 0.9]

clampScope

Maps a value to a relative range and clamps the result within another range.

clampScope(0.36, [0.35, 1]);
// => 0.015384 (relative progress of 0.36 within [0.35, 1], clamped to [0, 1])

clampScope(0.36, [0.35, 1], [0.1, 1]);
// => 0.1 (relative progress of 0.36 within [0.35, 1], clamped to [0.1, 1])

inRange

Determines if a value lies within a specified range (inclusive of the range boundaries).

inScope(0, 0, 1);
// => true (0 is within the range [0, 1])

inScope(1, 0, 1);
// => true (1 is within the range [0, 1])

inScope(2, 0, 1);
// => false (2 is outside the range [0, 1])

inScope(-1, 0, 1);
// => false (-1 is outside the range [0, 1])

lerp

Performs linear interpolation (LERP) between a current value and a target value using an easing factor.

lerp(0, 1, 0.4);
// => 0.4 (40% progress from 0 to 1)

lerp(0.75, 0.8, 0.98);
// => 0.799 (close to the target but not exactly 0.8)

lerp(0.75, 0.8, 0.98, 0.01);
// => 0.8 (within the approximation threshold `0.01`)

loop

Loops a value within a specified range.

If the value exceeds max, it wraps back to min. If it's below min, it wraps around to max.

loop(0, 0, 3); // => 0
loop(1, 0, 3); // => 1
loop(2, 0, 3); // => 2
loop(3, 0, 3); // => 0 (wraps back to the start)
loop(-1, 0, 3); // => 2 (wraps from below to the end)
loop(-2, 0, 3); // => 1
loop(-3, 0, 3); // => 0

easing

Applies an easing function to a given progress value.

This function calculates eased progress using a specified easing function, bezier curve, or custom easing function.

easing(0.35, EaseInBounce);
// => 0.167 (eased progress using EaseInBounce)

easing(0.35, [0.25, 0.1, 0.25, 1]);
// => 0.604 (eased progress using a bezier curve)

easing(0.35, (value) => Math.sin(Math.PI * 0.5 * value));
// => 0.522 (eased progress using a custom easing function)

Easing Types

  • A function. F.e. (value) => Math.sin(Math.PI * 0.5 * value)
  • A bezier curve array. F.e. [0.25, 0.1, 0.25, 1]
  • EaseInBack
  • EaseInBounce
  • EaseInCirc
  • EaseInCubic
  • EaseInElastic
  • EaseInExpo
  • EaseInOutBack
  • EaseInOutBounce
  • EaseInOutCirc
  • EaseInOutCubic
  • EaseInOutElastic
  • EaseInOutExpo
  • EaseInOutQuad
  • EaseInOutQuart
  • EaseInOutQuint
  • EaseInOutSine
  • EaseInQuad
  • EaseInQuart
  • EaseInQuint
  • EaseInSine
  • EaseOutBack
  • EaseOutBounce
  • EaseOutCirc
  • EaseOutCubic
  • EaseOutElastic
  • EaseOutExpo
  • EaseOutQuad
  • EaseOutQuart
  • EaseOutQuint
  • EaseOutSine

addEventListener

A utility function to add an event listener to a specified element.

The uility returns a function that can be called to remove the listener.

const button = document.getElementById('myButton');
const removeClickListener = addEventListener(button, 'click', (event) => {
console.log('Button clicked!');
});

// To remove the event listener later
removeClickListener();

normalizeWheel

Normalize wheel delta. This function is re-exported from normalize-wheel for convenience.

It helps normalize the wheel event's delta values (spinX, spinY, pixelX, pixelY) across different browsers.

document.addEventListener('wheel', (event) => {
const normalized = normalizeWheel(event);
console.log(normalized);
// => { spinX: -0, spinY: 1.25, pixelX: -0, pixelY: 125 }
});

onResize

Adds resize listeners to elements (using ResizeObserver) and/or the viewport.

Check viewport to understand viewportTarget in detail.

const resizeWithElement = onResize({
callback: () => console.log('Element resized'),
element: document.getElementById('app'),
});

const resizeWithViewport = onResize({
callback: () => console.log('Viewport resized'),
viewportTarget: 'width',
});

const resizeWithBoth = onResize({
callback: () => console.log('Both resized'),
element: document.getElementById('app'),
viewportTarget: 'any',
});

// Destroy
resizeWithBoth.remove();

toPixels

Transform value to pixels. Supported units: px | 'rem' | 'vw' | 'vh' | 'svh'.

toPixels('100px'); // => 100
toPixels('1vw'); // => 19.20