For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/en/components/input-number.md.

InputNumber

Enter numeric values such as quantities or prices.

Basic usage

Set bounds with min and max. onChange returns a number, or null when cleared. Partial minus signs and decimal points are preserved while typing; blur or Enter normalizes bounds and precision.

Quantity: 3
basic.tsx
import { Form, FormField, InputNumber, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function InputNumberBasic() {
  const [value, setValue] = useState<number | null>(3);

  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="Quantity">
        <InputNumber name="quantity" min={0} max={20} value={value} onChange={setValue} />
      </FormField>
      <Text tone="muted" role="status">
        Quantity: {value ?? 'Empty'}
      </Text>
    </Form>
  );
}

Examples

Units and decimals

Display units with prefix and suffix, and set the step and decimal places with step and precision. Use controls={false} to hide step buttons.

units.tsx
import { Form, FormField, InputNumber } from '@ifhover/leaf-ui';

export function InputNumberUnits() {
  return (
    <Form layout="vertical">
      <FormField label="Amount">
        <InputNumber min={0} step={0.1} precision={2} defaultValue={19.9} prefix="$" />
      </FormField>
      <FormField label="Percentage">
        <InputNumber defaultValue={50} min={0} max={100} suffix="%" controls={false} />
      </FormField>
    </Form>
  );
}

Read only and disabled

Read-only fields retain their value without allowing edits; disabled fields cannot be interacted with.

states.tsx
import { Form, FormField, InputNumber } from '@ifhover/leaf-ui';

export function InputNumberStates() {
  return (
    <Form layout="vertical">
      <FormField label="Read only">
        <InputNumber defaultValue={12} readOnly />
      </FormField>
      <FormField label="Disabled">
        <InputNumber defaultValue={8} disabled />
      </FormField>
    </Form>
  );
}

Display formatting

Use grouping for localized digit grouping. For custom formats, formatter controls display and parser converts the entered text back into a value. Formatting does not change the canonical value submitted by a native form.

formatting.tsx
import { Form, FormField, InputNumber } from '@ifhover/leaf-ui';

export function InputNumberFormatting() {
  return (
    <Form layout="vertical">
      <FormField label="Digit grouping">
        <InputNumber defaultValue={12345.67} precision={2} grouping />
      </FormField>
      <FormField label="Custom percentage">
        <InputNumber
          defaultValue={15}
          min={0}
          max={100}
          formatter={(value) => (value == null ? '' : `${value}%`)}
          parser={(text) => text.replace('%', '')}
        />
      </FormField>
    </Form>
  );
}

Exact decimal values

Use stringMode for values beyond JavaScript Number precision. Pass strings for value, defaultValue, step, min and max; onChange returns a string or null. Do not convert these values to Number first.

Current value: 9007199254740993.01
exact.tsx
import { Form, FormField, InputNumber, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function InputNumberExact() {
  const [value, setValue] = useState<string | null>('9007199254740993.01');

  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="Exact amount">
        <InputNumber
          stringMode
          name="amount"
          value={value}
          onChange={setValue}
          step="0.01"
          precision={2}
        />
      </FormField>
      <Text tone="muted" role="status">
        Current value: {value ?? 'Empty'}
      </Text>
    </Form>
  );
}

API

InputNumber API

Forms

Set name to submit the canonical value through FormData. Uncontrolled fields support form reset; reset controlled values in application state. Native attributes such as required and form reach the input. See Form for form integration.

PropertyTypeDefaultDescription
valuenumber | null | string—Controlled number, or string in stringMode; null represents an empty field.
defaultValuenumber | null | stringnullInitial uncontrolled value, a string in stringMode; restored on form reset.
onChange((value: number | null) => void) | ((value: string | null) => void)—Called for a valid number or clearing
minnumber | stringUnboundedAllowed number range
maxnumber | stringUnboundedAllowed number range
stepnumber | string1Increment and decrement step
precisionnumber—Decimal precision, from 0 to 15
controlsbooleantrueShow increment and decrement buttons
keyboardbooleantrueSupport arrow key increments
size'sm' | 'md' | 'lg''md'Control size
status'error' | 'warning'—Validation status
prefixReactNode—Leading / trailing decoration
suffixReactNode—Leading / trailing decoration
stringModefalse | true—Use strings for exact values, steps and bounds.
formatter( value: number | string | null, info: { userTyping: boolean; input: string }, ) => string—Format displayed text without changing the canonical form value.
parser(text: string) => number | string—Parse displayed text back into a value.
groupingboolean—Use localized digit grouping.
localestring—Locale for language or numeric formatting.
disabledbooleanfalseDisable interaction.
readOnlybooleanfalseLock the value against typing, selection, clearing and removal.
refRef<HTMLInputElement>—Input element ref

NumericInputNumber API

Only mode-specific type differences are listed here; see the main API table for shared props.

PropertyTypeDefaultDescription
valuenumber | null—Controlled value.
defaultValuenumber | nullnullInitial value; uncontrolled fields support native form reset.
onChange(value: number | null) => void—Called when the value changes.
minnumber—Minimum allowed value.
maxnumber—Maximum allowed value.
stepnumber1Increment and decrement step.
stringModefalse—Numeric mode; omit or pass false. Values and callbacks use numbers.
formatter( value: number | string | null, info: { userTyping: boolean; input: string }, ) => string—Format displayed text without changing the canonical form value.
parser(text: string) => number | string—Parse displayed text back into a value.

StringInputNumber API

Only mode-specific type differences are listed here; see the main API table for shared props.

PropertyTypeDefaultDescription
formatter( value: number | string | null, info: { userTyping: boolean; input: string }, ) => string—Format displayed text without changing the canonical form value.
parser(text: string) => number | string—Parse displayed text back into a value.
stringModetrueRequiredHigh-precision string mode; pass true and use strings for values, steps and bounds.
valuestring | null—Controlled value.
defaultValuestring | nullnullInitial value; uncontrolled fields support native form reset.
onChange(value: string | null) => void—Called when the value changes.
minstring—Minimum allowed value.
maxstring—Maximum allowed value.
stepstring'1'Increment and decrement step.