FarazzShaikh/i-input

An intelligent universal numeric input for React.

Summary

i-input is a React numeric input component inspired by Blender's number fields, offering drag-to-scrub, inline math evaluation, and unit-aware parsing in one package. It ships as a styled <IInput /> component plus a headless useIInput hook for fully custom rendering, and is written in TypeScript under the MIT license.

What it is useful for

i-input fits situations where a plain <input type="number"> is too rigid. It is useful for:

• Numeric controls in creative or 3D-style tools, where users expect to drag horizontally or vertically to change a value rather than type.
• Form fields with units, since users can type values like 5km, 3ft 2in, or 1m + 2cm and the library converts them to the configured base unit (meters, in the built-in distanceUnits system).
• Constrained inputs with soft and hard limits: softMin/softMax cap scrubbing and stepping, while hardMin/hardMax also clamp typed values.
• Wrap-around values such as angles (0°→360°), configured via the wrapMode option.
• Custom overlays like progress bars, fill indicators, or buttons, rendered through a child function that receives live state and actions.
• Inline math evaluation on commit, e.g. typing 3 * 2 + 1 resolves to 7.

How engineers can use it

Install with npm install i-input (or yarn add i-input). react and react-dom >= 18 are listed as peer dependencies.

The quickest start is a controlled component:

import { useState } from "react";
import { IInput } from "i-input";

function Example() {
  const [value, setValue] = useState(0);
  return <IInput value={value} onChange={setValue} />;
}

For unit-aware editing, pass a unit system:

import { IInput, distanceUnits } from "i-input";

<IInput
  value={meters}
  onChange={setMeters}
  unit="m"
  unitSystem={distanceUnits}
/>
// accepts "5km", "3ft 2in", "1m + 2cm"

If the default styling does not fit your design, the useIInput hook returns bindRoot, bindInput, state (including editing, dragging, normalized), and actions (stepBy, negate, set). Custom unit systems are defined as { baseNames, units: [{ names, toBase }] }.

Documented interactions include: drag to scrub (hold Shift for fine steps, Ctrl/Cmd for precision), arrow keys or wheel to step, Enter to commit, and Escape to cancel. Documented scope: only distanceUnits is bundled; any other system (time, weight, etc.) must be defined by the user, and the README does not specify the full grammar of supported math expressions.