# near-field

> Cursor proximity as a CSS input, for React or plain JavaScript. One tiny import exposes how close the pointer is to an element as CSS custom properties, plus three pre-tuned effects (Magnetic, Tilt, Glow) built on that primitive. Core is about 1.5KB min+gzip, zero dependencies, React 18 and 19, or no framework via near-field/vanilla.

Hover is binary; CSS has nothing between "not hovering" and "hovering". near-field provides the continuum. One module-level pointer field (one passive pointermove listener, one shared requestAnimationFrame loop) serves any number of subscribed elements. Distances are computed against cached rects, refreshed via ResizeObserver and on scroll end. Springs are a semi-implicit Euler integrator at a fixed 120Hz substep.

## Install

npm install near-field

## The primitive: useNearField

const ref = useNearField({ radius: 140 });
// attach ref to an element; it then carries:
// --nf   eased proximity, 0 far away to 1 touching or inside the element
// --nf-x, --nf-y   unit vector from the element center toward the pointer

Options: radius (px, default 140), onFrame (callback with raw frame data), cssVars (default true), disabled.
Frame fields: proximity (eased 0..1), distance (px from nearest edge, 0 inside), vector {x, y}, localX, localY (pointer relative to the element), width, height.
Zero re-renders: everything is written outside the React render cycle.

Example CSS:

.card {
  transform: translate(
    calc(var(--nf-x) * var(--nf) * 8px),
    calc(var(--nf-y) * var(--nf) * 8px)
  );
}

## Components

All accept radius, feel ("gentle" | "snappy" | "instant"), as (element type), and arbitrary HTML attributes.

<Magnetic strength={0.3}> pulls its content toward the cursor inside the field and springs back when it leaves. strength is 0..1, default 0.3.

<Tilt max={6} perspective={800}> tilts toward the cursor, eased in by proximity. max in degrees, default 6.

<Glow color="rgba(125, 170, 255, 0.35)" size={160}> is a soft light that tracks the cursor and brightens with proximity. size is the gradient radius in px.

## Vanilla (no React): near-field/vanilla

The same primitive and effects with no framework. React never enters the bundle (about 3KB min+gzip with all three effects); the React peer dependency is optional.

import { nearField, magnetic, tilt, glow } from "near-field/vanilla";

const stop = nearField(el, { radius: 140 });   // same options as useNearField minus disabled
magnetic(el, { strength: 0.3 });
tilt(el, { max: 6 });
glow(el, { color: "rgba(120, 170, 255, 0.3)" });

Each function takes an existing HTMLElement and returns a cleanup that unregisters it and restores its inline styles. The effects take the same options as their components minus as (they attach to your element instead of rendering a wrapper), and share the same field, springs, reduced-motion handling, and touch press states. The entry also re-exports the framework-free core (registerElement, computeFrame, createSpring, springPresets, prefersReducedMotion, subscribeReducedMotion) for building custom adapters.

No bundler needed: the build uses only relative imports, so plain HTML can load it from a CDN inside <script type="module">:
import { glow } from "https://cdn.jsdelivr.net/npm/near-field@0.2/dist/vanilla.js";

## Behavior

- prefers-reduced-motion: Magnetic and Tilt collapse to rest. Glow is opacity-only and may opt in to remain with respectReducedMotion={false}.
- Touch and coarse pointers: the field never activates; components degrade to a tuned press state.
- SSR-safe: no window access at import time.

## Links

- Site: https://nearfield.thilina.dev
- Docs: https://nearfield.thilina.dev/docs
- Lab (interactive playground): https://nearfield.thilina.dev/lab
- npm: https://www.npmjs.com/package/near-field
- GitHub: https://github.com/itsthilinar/near-field