NumberField

Description

A numeric input field component with support for min/max validation, decimal numbers, and unit display. Automatically converts values to numbers and integrates with React Hook Form.

Import

import { NumberField } from '@components/common/form/NumberField';

Usage

import { Form } from '@components/common/form/Form';
import { NumberField } from '@components/common/form/NumberField';

function ProductForm() {
  return (
    <Form action="/api/products">
      <NumberField
        name="price"
        label="Price"
        min={0}
        unit="$"
        unitPosition="left"
        required
      />
    </Form>
  );
}

Props

Name	Type	Default	Description
name	string	-	Field name (required)
label	string	-	Label text displayed above the input
min	number	-	Minimum allowed value
max	number	-	Maximum allowed value
step	number	-	Increment/decrement step value
allowDecimals	boolean	true	Whether to allow decimal numbers
unit	string	-	Unit label to display (e.g., '$', 'kg', '%')
unitPosition	'left' | 'right'	'right'	Position of the unit label
required	boolean	false	Makes the field required
defaultValue	number	-	Default numeric value
error	string	-	Custom error message
helperText	string	-	Helper text shown in a tooltip
validation	RegisterOptions	-	React Hook Form validation rules
onChange	(value: number | null) => void	-	Callback fired when the value changes
prefixIcon	React.ReactNode	-	Icon displayed on the left inside the input
suffixIcon	React.ReactNode	-	Icon displayed on the right inside the input
wrapperClassName	string	-	CSS class for the wrapper div
...props	InputHTMLAttributes	-	All standard HTML input attributes

Example: Price Field

import { Form } from '@components/common/form/Form';
import { NumberField } from '@components/common/form/NumberField';

function PriceForm() {
  return (
    <Form action="/api/pricing">
      <NumberField
        name="price"
        label="Product Price"
        min={0}
        step={0.01}
        unit="$"
        unitPosition="left"
        required
        helperText="Enter the product price in USD"
      />
    </Form>
  );
}

Example: Quantity Field

import { Form } from '@components/common/form/Form';
import { NumberField } from '@components/common/form/NumberField';

function InventoryForm() {
  return (
    <Form action="/api/inventory">
      <NumberField
        name="quantity"
        label="Stock Quantity"
        min={0}
        max={10000}
        allowDecimals={false}
        required
        validation={{
          validate: (value) =>
            value > 0 || 'Quantity must be greater than zero'
        }}
      />
    </Form>
  );
}

Example: Percentage Field

import { Form } from '@components/common/form/Form';
import { NumberField } from '@components/common/form/NumberField';

function DiscountForm() {
  return (
    <Form action="/api/discount">
      <NumberField
        name="discount"
        label="Discount"
        min={0}
        max={100}
        step={5}
        unit="%"
        unitPosition="right"
        defaultValue={10}
      />
    </Form>
  );
}

Example: Weight Field

import { Form } from '@components/common/form/Form';
import { NumberField } from '@components/common/form/NumberField';

function ShippingForm() {
  return (
    <Form action="/api/shipping">
      <NumberField
        name="weight"
        label="Package Weight"
        min={0.1}
        step={0.1}
        unit="kg"
        unitPosition="right"
        required
      />
    </Form>
  );
}

Features

• Automatic Number Conversion: Values are converted to numbers automatically
• Min/Max Validation: Built-in validation for value ranges
• Decimal Support: Control whether decimal numbers are allowed
• Unit Display: Show currency, measurement, or percentage units
• Null Handling: Returns null for empty values instead of NaN
• Icon Support: Add prefix or suffix icons

Value Handling

• Empty values are converted to null
• Invalid inputs return null
• If allowDecimals is false, uses parseInt()
• If allowDecimals is true, uses parseFloat()

Related Components

• Form - Parent form component
• RangeField - Slider input for numbers
• InputField - General text input