> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.

# InputNumber

Data Entry`@rockshin/tao-ui`

[Examples](#examples)[API](#api)

A styled numeric input built on tao-ui number formatting and validation behavior.

## When to use

Use InputNumber for numeric values that need min, max, step, precision, or formatted display.

**Recommended**

- Set min and max when the domain is bounded.
- Use the headless API when custom rendering is required.

**Avoid**

- Do not use a numeric input for identifiers such as account numbers.

## Examples


### Basic usage
```tsx preview
import { InputNumber } from '@rockshin/tao-ui';
import { useState } from 'react';

function InputNumberExample() {
  const [value, setValue] = useState('1500');

  return (
    <InputNumber
      value={value}
      onChange={setValue}
      prefix="$"
      suffix="USD"
      decimalPlaces={2}
      thousandsSeparator=","
    />
  );
}

export default InputNumberExample;
```

### Currency and percentage
```tsx preview
import { InputNumber, Stack } from '@rockshin/tao-ui';

function InputNumberFormats() {
  return (
    <Stack gap="md">
      <InputNumber
        defaultValue="150000"
        prefix="€"
        decimalPlaces={2}
        thousandsSeparator=","
      />
      <InputNumber
        defaultValue="0.42"
        isPercentage
        suffix="%"
        decimalPlaces={1}
      />
    </Stack>
  );
}

export default InputNumberFormats;
```

### Sizes, variants, and bounds
```tsx preview
import { InputNumber, Stack } from '@rockshin/tao-ui';

function InputNumberStates() {
  return (
    <Stack gap="md">
      <InputNumber size="small" variant="outlined" placeholder="Small" />
      <InputNumber
        size="medium"
        variant="filled"
        min={0}
        max={100}
        defaultValue="50"
      />
      <InputNumber size="large" variant="borderless" error defaultValue="120" />
    </Stack>
  );
}

export default InputNumberStates;
```

### Currency formatting
Thousands separators, decimals, and a prefix format display while retaining a usable value.
```tsx preview
import { useState } from 'react';

import { InputNumber } from '@rockshin/tao-ui';

function ControlledWrapper(props: React.ComponentProps<typeof InputNumber>) {
  const [value, setValue] = useState((props.value as string | undefined) ?? '');
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 12,
        minWidth: 0,
        width: '100%',
        maxWidth: 320,
      }}
    >
      <InputNumber
        {...props}
        value={value}
        onChange={(v) => {
          setValue(v);
          props.onChange?.(v);
        }}
      />
      <code
        style={{
          background: 'var(--tao-color-bg-container)',
          padding: 8,
          borderRadius: 4,
        }}
      >
        actual value: {JSON.stringify(value)}
      </code>
    </div>
  );
}

export default function InputNumberCurrency() {
  const args: React.ComponentProps<typeof InputNumber> = {
    prefix: '€',
    thousandsSeparator: ',',
    decimalSeparator: '.',
    decimalPlaces: 2,
    value: '150000',
    placeholder: 'Amount',
  };
  return <ControlledWrapper {...args} />;
}
```

### Prefix and suffix
Use affixes for units instead of storing them in the numeric value.
```tsx preview
import { useState } from 'react';

import { InputNumber } from '@rockshin/tao-ui';

function ControlledWrapper(props: React.ComponentProps<typeof InputNumber>) {
  const [value, setValue] = useState((props.value as string | undefined) ?? '');
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 12,
        minWidth: 0,
        width: '100%',
        maxWidth: 320,
      }}
    >
      <InputNumber
        {...props}
        value={value}
        onChange={(v) => {
          setValue(v);
          props.onChange?.(v);
        }}
      />
      <code
        style={{
          background: 'var(--tao-color-bg-container)',
          padding: 8,
          borderRadius: 4,
        }}
      >
        actual value: {JSON.stringify(value)}
      </code>
    </div>
  );
}

export default function InputNumberWithSuffix() {
  const args: React.ComponentProps<typeof InputNumber> = {
    suffix: 'USD',
    prefix: '$',
    decimalPlaces: 2,
    placeholder: 'Try 1234567',
  };
  return <ControlledWrapper {...args} />;
}
```

### Three sizes
Compare three control sizes with the same numeric behavior.
```tsx preview
import { InputNumber } from '@rockshin/tao-ui';

export default function InputNumberSizes() {
  const args: React.ComponentProps<typeof InputNumber> = {
    thousandsSeparator: ',',
  };
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 12,
        minWidth: 0,
        width: '100%',
        maxWidth: 320,
      }}
    >
      <InputNumber {...args} size="small" prefix="¥" value="1000" />
      <InputNumber {...args} size="medium" prefix="¥" value="1000" />
      <InputNumber {...args} size="large" prefix="¥" value="1000" />
    </div>
  );
}
```

### Visual variants
Keep the same controlled input behavior across visual variants.
```tsx preview
import { InputNumber } from '@rockshin/tao-ui';

export default function InputNumberVariants() {
  const args: React.ComponentProps<typeof InputNumber> = {
    thousandsSeparator: ',',
  };
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 12,
        minWidth: 0,
        width: '100%',
        maxWidth: 320,
      }}
    >
      <InputNumber {...args} variant="outlined" prefix="¥" value="1000" />
      <InputNumber {...args} variant="filled" prefix="¥" value="1000" />
      <InputNumber {...args} variant="borderless" prefix="¥" value="1000" />
    </div>
  );
}
```

### Percentages
Set decimal precision and a percent suffix; this example does not convert between percentages and fractions.
```tsx preview
import { useState } from 'react';

import { InputNumber } from '@rockshin/tao-ui';

function ControlledWrapper(props: React.ComponentProps<typeof InputNumber>) {
  const [value, setValue] = useState((props.value as string | undefined) ?? '');
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 12,
        minWidth: 0,
        width: '100%',
        maxWidth: 320,
      }}
    >
      <InputNumber
        {...props}
        value={value}
        onChange={(v) => {
          setValue(v);
          props.onChange?.(v);
        }}
      />
      <code
        style={{
          background: 'var(--tao-color-bg-container)',
          padding: 8,
          borderRadius: 4,
        }}
      >
        actual value: {JSON.stringify(value)}
      </code>
    </div>
  );
}

export default function InputNumberPercentage() {
  const args: React.ComponentProps<typeof InputNumber> = {
    isPercentage: true,
    decimalPlaces: 2,
    suffix: '%',
    placeholder: 'Type 50 → actual is 0.5',
  };
  return <ControlledWrapper {...args} />;
}
```

### Numeric bounds
Set the accepted range and observe the value during editing and on blur.
```tsx preview
import { useState } from 'react';

import { InputNumber } from '@rockshin/tao-ui';

function ControlledWrapper(props: React.ComponentProps<typeof InputNumber>) {
  const [value, setValue] = useState((props.value as string | undefined) ?? '');
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 12,
        minWidth: 0,
        width: '100%',
        maxWidth: 320,
      }}
    >
      <InputNumber
        {...props}
        value={value}
        onChange={(v) => {
          setValue(v);
          props.onChange?.(v);
        }}
      />
      <code
        style={{
          background: 'var(--tao-color-bg-container)',
          padding: 8,
          borderRadius: 4,
        }}
      >
        actual value: {JSON.stringify(value)}
      </code>
    </div>
  );
}

export default function InputNumberClampedRange() {
  const args: React.ComponentProps<typeof InputNumber> = {
    min: 0,
    max: 100,
    decimalPlaces: 0,
    placeholder: 'Type 999, blur to clamp to 100',
  };
  return <ControlledWrapper {...args} />;
}
```

## Regional formatting

Regional grouping, decimal symbols and digits inherit `TaoProvider.locale.numberLocale`; set `locale="fr-FR"` on this component to override it. Explicit separators take precedence. Numeric input keeps canonical ASCII strings and precision while displaying localized digits.

## API


### [#](#inputnumber)InputNumber



| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| disabled | Whether to disable | `boolean | undefined` | `-` |
| className | Additional css class | `string | undefined` | `-` |
| locale | BCP 47 locale. Defaults to the provider's number locale. | `string | undefined` | `-` |

