clamp

Restricts a number to be within a specified range. Ensures that a value stays within the bounds defined by minimum and maximum values. If the value exceeds the bounds, it returns the boundary value. Commonly used for constraining user input, animation values, or preventing overflow in calculations.

Signature

const clamp: (value: number, min: number, max: number) => number

Parameters

Name	Type	Description
value	-	The number to be clamped
min	-	The lower boundary of the range
max	-	The upper boundary of the range

Returns

The clamped value within [min, max] range

Examples

Basic range restriction

import { clamp } from '@winglet/common-utils';

console.log(clamp(5, 0, 10));   // 5 (within range)
console.log(clamp(-5, 0, 10));  // 0 (below minimum)
console.log(clamp(15, 0, 10));  // 10 (above maximum)
console.log(clamp(0.5, 0, 1));  // 0.5 (works with decimals)

UI element positioning

function constrainPosition(x: number, y: number) {
  const viewportWidth = window.innerWidth;
  const viewportHeight = window.innerHeight;

  return {
    x: clamp(x, 0, viewportWidth),
    y: clamp(y, 0, viewportHeight)
  };
}

Playground

import { clamp } from '@winglet/common-utils';

console.log(clamp(5, 0, 10));   // 5 (within range)
console.log(clamp(-5, 0, 10));  // 0 (below minimum)
console.log(clamp(15, 0, 10));  // 10 (above maximum)
console.log(clamp(0.5, 0, 1));  // 0.5 (works with decimals)

Notes

Special Cases:

• When min equals max, always returns that value
• Handles Infinity: clamps to boundary values
• Returns NaN if value is NaN

Use Cases:

• Constraining user input values
• Limiting animation parameters
• Preventing array index overflow
• Color value normalization (0-255 or 0-1)
• Volume/brightness controls