---
title: "mapRange"
description: "Linearly map a number from one range to another, with optional clamping to the output range."
canonical_url: "https://core.mhaibaraai.cn/en/docs/utilities/math/map-range"
---
# mapRange

> Linearly map a number from one range to another, with optional clamping to the output range.

## Usage

`mapRange` maps a number from an input range to an output range, keeping the ratio linear.

```ts
import { mapRange } from '@movk/core'

mapRange(5, [0, 10], [0, 100]) // 50
mapRange(0, [0, 10], [4, 20]) // 4
mapRange(10, [0, 10], [4, 20]) // 20
mapRange(0, [-10, 10], [0, 100]) // 50
```

### Extrapolation and Clamping

Out-of-range inputs are extrapolated linearly by default. Pass `{ clamp: true }` to constrain the result to the output range.

```ts
mapRange(20, [0, 10], [0, 100]) // 200
mapRange(-5, [0, 10], [0, 100]) // -50

mapRange(20, [0, 10], [0, 100], { clamp: true }) // 100
mapRange(-5, [0, 10], [0, 100], { clamp: true }) // 0
```

### Reversed Output Range

The output range may be written in reverse for "larger input, smaller result" mappings. Clamping still applies.

```ts
mapRange(0, [0, 10], [20, 4]) // 20
mapRange(5, [0, 10], [20, 4]) // 12
mapRange(10, [0, 10], [20, 4]) // 4
```

### Collapsed Input Range

When both ends of `inRange` are equal the ratio is undefined, so the first end of the output range is returned instead of an `Infinity` or `NaN` produced by dividing by zero.

```ts
mapRange(5, [3, 3], [10, 20]) // 10
```

### Typical Use Case

When mapping node degree to node size, extreme values outside the measured range should not break the visual upper bound:

```ts
const size = mapRange(degree, [minDegree, maxDegree], [4, 20], { clamp: true })
```

## API

### `mapRange(value, inRange, outRange, options?)`

Linearly map a number from one range to another.

### Parameters

**value** (`number`) *required*: The number to map.

**inRange** (`readonly [number, number]`) *required*: Input range [min, max]; may be reversed.

**outRange** (`readonly [number, number]`) *required*: Output range [min, max]; may be reversed.

**options** (`MapRangeOptions`): Mapping behavior options.

### Returns

**returns** (`number`): The mapped number.

### MapRangeOptions

**clamp** (`boolean`): Whether to constrain the result to outRange. Defaults to false.

## Changelog

See commit history for [src/utilities/math/mapRange.ts](https://github.com/mhaibaraai/movk-core/commits/main/src/utilities/math/mapRange.ts).

---

- [GitHub](https://github.com/mhaibaraai/movk-core/blob/main/src/utilities/math/mapRange.ts)


## Sitemap

See the full [sitemap](https://core.mhaibaraai.cn/sitemap.md) for all pages.