web3-ui

A react library developed with dumi

Usage

Install

npm i web3-ui-react

Components

InputNumber

InputNumber provides a lightweight and flexible number input solution, supporting both:

🪝 Hook API — useInputNumber (UI-agnostic)

🧱 Component API — <InputNumber /> (built on top of antd’s <Input>)

✨ Features

✅ Thousand separators formatting

✅ Cursor position auto recovery

✅ Built-in min, max, required, and custom validators

✅ Automatic error callback

✅ Supports decimal precision (precision)

✅ Works both as a hook and as a ready-to-use component

📦 Usage — Hook

import { Button, Space } from 'antd';
import React, { useMemo, useState } from 'react';
import {
  InputNumber,
  InputValidatorError,
  isNaN,
  toFixed,
  useInputNumber,
} from 'web3-ui-react';

export default () => {
  const [inputValidErr, setInputValidErr] = useState<InputValidatorError>();
  const { inputProps, value } = useInputNumber({
    min: 0,
    precision: 18,
    required: true,
    onInputErr: (e) => setInputValidErr(e),
  });
  const isNaNErr = useMemo(
    () => (isNaN(value) ? new Error('Invalid number type') : undefined),
    [value],
  );
  const err = useMemo(
    () => inputValidErr || isNaNErr,
    [inputValidErr, isNaNErr],
  );
  return (
    <div>
      <Space.Compact>
        <InputNumber {...inputProps} />
        <Button
          disabled={!!err}
          onClick={() => {
            const parsedValue = toFixed(value!);
            // You can use Number(parsedValue) or BigInt(parsedValue) or BigNumber(parsedValue) or use parsedValue directly.
          }}
        >
          Submit
        </Button>
      </Space.Compact>
      {err && <div className="err">{err.message}</div>}
    </div>
  );
};

📦 Usage — Antd Component

import { Button, Space } from 'antd';
import React, { useMemo, useState } from 'react';
import {
  InputNumber,
  InputValidatorError,
  isNaN,
  toFixed,
} from 'web3-ui-react';

export default () => {
  const [value, setValue] = useState('');
  const [inputValidErr, setInputValidErr] = useState<InputValidatorError>();
  const isNaNErr = useMemo(
    () => (isNaN(value) ? new Error('Invalid number type') : undefined),
    [value],
  );
  const err = useMemo(
    () => inputValidErr || isNaNErr,
    [inputValidErr, isNaNErr],
  );
  return (
    <div>
      <Space.Compact>
        <InputNumber
          value={value}
          onChange={(e) => setValue(e.target.value)}
          onInputErr={(e) => setInputValidErr(e)}
          min={0}
          precision={18}
          format
          required
        />
        <Button
          disabled={!!err}
          onClick={() => {
            const parsedValue = toFixed(value);
            // You can use Number(parsedValue) or BigInt(parsedValue) or BigNumber(parsedValue) or use parsedValue directly.
          }}
        >
          Submit
        </Button>
      </Space.Compact>
      {err && <div className="err">{err.message}</div>}
    </div>
  );
};

Props

| Prop | Type | Description | | ---------------- | --------------------------------------- | -------------------------------------- | | All InputProps | from antd | Inherits all standard antd Input props | | min | number \| string | Minimum value | | max | number \| string | Maximum value | | required | boolean | Whether the field is required | | precision | number | Decimal precision | | format | boolean | Thousand separators formatting | | validator | Validator | Custom validation function set | | onInputErr | (error?: InputValidatorError) => void | Triggered when validation fails |

🧪 validator — Custom Validation

validator lets you define custom error messages or validation rules in addition to the built-in min / max / required. 💡 If validator is provided and the rule returns a string, that string will be wrapped in an InputValidatorError and passed to onInputErr.

export interface Validator {
  min?: (min: number, value: string) => string;
  max?: (max: number, value: string) => string;
  required?: () => string;
  validate?: (value: string) => string | undefined | void;
}

Example: Custom Validator

import React from 'react';
import { InputNumber, InputValidatorError } from 'web3-ui-react';

export default () => (
  <InputNumber
    min={0}
    max={1000}
    validator={{
      min: (min: number, value: string) => `Value must be ≥ ${min}, but got ${value}`,
      max: (max: number, value: string) => `Value must be ≤ ${max}, but got ${value}`,
      required: () => '⚠️ This field is required!',
      validate: (value: string) => {
        if (Number(value) % 2 !== 0) {
          return 'Value must be an even number';
        }
      },
    }}
    required
    onInputErr={(err?: InputValidatorError) => {
      if (err) {
        console.log(`[${err.type}] ${err.message}`);
      }
    }}
  />
);

✅ In the example above:

min and max will override the default error message.

validate func checks if the value is even.

All errors are reported through onInputErr.

🧭 Notes

✅ InputNumber behaves like a normal antd <Input> component, so it supports Form.Item, value, onChange, etc.

✅ onInputErr provides additional validation feedback independent from Form rules.

🚀 If you need to integrate with a different UI library, please use useInputNumber directly.

🧮 Utility Functions

Besides the useInputNumber hook and InputNumber component, this package also exports a few utility functions to help handle numeric input.

isNaN(value: unknown): boolean

💡 This method is especially useful when validating input before parsing it to a number.

This helper function determines whether the given value is not a valid number string. Unlike the native Number.isNaN, this function also works with strings and filters out invalid numeric formats.

import { isNaN } from 'demo';

isNaN(null);           // true
isNaN(undefined);      // true
isNaN('abc_222');      // true (invalid number string)
isNaN('-000.2334');    // false
isNaN('000.222');      // false
isNaN('-22.333');      // false
isNaN(123);            // false
isNaN(NaN);            // true

| Input | Result | Explanation | | -------------------- | ------- | --------------------------- | | null / undefined | ✅ true | Treated as invalid number | | Function | ✅ true | Not a number | | 'abc_222' | ✅ true | Contains invalid characters | | '-000.2334' | ❌ false | Valid numeric string | | '000.222' | ❌ false | Valid numeric string | | '-22.333' | ❌ false | Valid numeric string | | 123 | ❌ false | Valid number | | NaN | ✅ true | Native NaN |

toFixed(value: string): string

💡 toFixed does not round decimals like Number.prototype.toFixed — it only normalizes the raw input string.

This utility cleans up the parsed value into a normalized number string, removing incomplete characters like trailing - or ..

import { toFixed } from 'demo';

toFixed('-');        // ''
toFixed('123.');     // '123'
toFixed('00123.45'); // '123.45'

| Input | Output | Explanation | | ------------ | ---------- | --------------------------------------- | | '-' | '' | A lone minus sign is considered invalid | | '123.' | '123' | Trailing dot removed | | '00123.45' | '123.45' | Leading zeros removed |

✅ These helpers are designed to work consistently with the input formatting and validation logic of InputNumber.

Development

# install dependencies
$ npm install

# develop library by docs demo
$ npm start

# build library source code
$ npm run build

# build library source code in watch mode
$ npm run build:watch

# build docs
$ npm run docs:build

# Locally preview the production build.
$ npm run docs:preview

# check your project for potential problems
$ npm run doctor