# near-field

> Cursor proximity as a CSS input for React. 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.

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.

## 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://project-near-field.vercel.app
- Lab (interactive playground): https://project-near-field.vercel.app/lab
- npm: https://www.npmjs.com/package/near-field
- GitHub: https://github.com/edward-126/near-field