# nearestDomainValue

Import from `@pibbl/core/viz`. `nearestDomainValue(values, rangeValue, scale)` accepts
plain numeric values and a resolved linear scale. It returns the original value
whose mapped position is closest, or undefined for empty/all-invalid input.
Equal distances choose the earliest source value. No sorting or inversion is
needed, including for collapsed ranges. The query must be finite; invalid source
values are skipped and arithmetic overflow throws. This pure O(n) helper owns
no observers or persistent cache.

## API details from source

<span id="api-nearestDomainValue"></span>

Finds the domain value nearest to a logical range coordinate; returns undefined for no
candidate.

```ts
nearestDomainValue: (values: readonly number[], rangeValue: number, scale: ResolvedContinuousScale) => number | undefined
```

Related API: [nearestDomainValue](/reference/functions/nearest-domain-value/), [ResolvedContinuousScale](/reference/functions/utc-domains/).

### Parameters

- **`values`** — Candidate domain values.

- **`rangeValue`** — Pointer coordinate in the scale's range.

- **`scale`** — Scale mapping candidates into range coordinates. See [ResolvedContinuousScale](/reference/functions/utc-domains/).

### Returns

The nearest domain value, or undefined when no candidate can be selected.

### See also

[ResolvedContinuousScale](/reference/functions/utc-domains/)

[View source — packages/core/src/features/viz/lib/nearest.ts:69](/source/packages/core/src/features/viz/lib/nearest-ts/#L69)

## Implementation guidance for agents

Read the [Data visualization companion](/agents/topics/visualization/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow.

## Complete minimal examples

- [Nearest-point lookup](/minimal-examples/viz/nearest/): Locate the nearest observation in pixel and domain space. [Plain source](/minimal/viz/nearest.ts)
## Documentation version

Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.