> 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.

# HeadlessInputNumber

Headless`@rockshin/tao-ui`

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

Headless numeric input primitives and hook for custom number entry experiences.

## When to use

Use the headless API when tao-ui styling is not appropriate but number formatting behavior should stay consistent.

**Recommended**

- Use useNumberInput for fully custom rendering.
- Reuse the validation helpers for parity with the styled InputNumber.

**Avoid**

- Do not use the component outside its intended interaction model.

## Examples


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

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

  return (
    <HeadlessInputNumber
      value={value}
      onChange={setValue}
      prefix="$"
      decimalPlaces={2}
      thousandsSeparator=","
      placeholder="Enter amount"
    />
  );
}

export default HeadlessInputNumberExample;
```

### Formatting and affixes
```tsx preview
import { HeadlessInputNumber, Stack } from '@rockshin/tao-ui';

function HeadlessNumberFormats() {
  return (
    <Stack gap="md">
      <HeadlessInputNumber
        defaultValue="1234567.5"
        prefix="$"
        suffix="USD"
        decimalPlaces={2}
        thousandsSeparator=","
      />
      <HeadlessInputNumber
        defaultValue="0.275"
        isPercentage
        suffix="%"
        decimalPlaces={1}
      />
    </Stack>
  );
}

export default HeadlessNumberFormats;
```

### Locale separators and bounds
```tsx preview
import { HeadlessInputNumber, Stack } from '@rockshin/tao-ui';

function HeadlessNumberConstraints() {
  return (
    <Stack gap="md">
      <HeadlessInputNumber
        defaultValue="1234.5"
        thousandsSeparator="."
        decimalSeparator=","
        decimalPlaces={2}
      />
      <HeadlessInputNumber
        defaultValue="50"
        min={0}
        max={100}
        suffix=" units"
      />
    </Stack>
  );
}

export default HeadlessNumberConstraints;
```

### Thousands separators
Configure grouping and decimal separators and compare display with the emitted value.
```tsx preview
import { useState } from 'react';

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

function ControlledWrapper(
  props: React.ComponentProps<typeof HeadlessInputNumber>,
) {
  const [value, setValue] = useState((props.value as string | undefined) ?? '');
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 12,
        minWidth: 0,
        width: '100%',
        maxWidth: 320,
      }}
    >
      <HeadlessInputNumber
        {...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 HeadlessInputNumberWithThousandSeparator() {
  const args: React.ComponentProps<typeof HeadlessInputNumber> = {
    placeholder: 'Try 1234567',
    decimalPlaces: 2,
    thousandsSeparator: ',',
    decimalSeparator: '.',
  };
  return <ControlledWrapper {...args} />;
}
```

### Affix formatting
Configure unit or currency affixes while the headless input handles numeric values.
```tsx preview
import { useState } from 'react';

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

function ControlledWrapper(
  props: React.ComponentProps<typeof HeadlessInputNumber>,
) {
  const [value, setValue] = useState((props.value as string | undefined) ?? '');
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 12,
        minWidth: 0,
        width: '100%',
        maxWidth: 320,
      }}
    >
      <HeadlessInputNumber
        {...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 HeadlessInputNumberWithPrefixSuffix() {
  const args: React.ComponentProps<typeof HeadlessInputNumber> = {
    prefix: '$',
    suffix: 'USD',
    decimalPlaces: 2,
  };
  return <ControlledWrapper {...args} />;
}
```

### Percentage values
Use a percent suffix and precision; define percentage conversion in application logic.
```tsx preview
import { useState } from 'react';

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

function ControlledWrapper(
  props: React.ComponentProps<typeof HeadlessInputNumber>,
) {
  const [value, setValue] = useState((props.value as string | undefined) ?? '');
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 12,
        minWidth: 0,
        width: '100%',
        maxWidth: 320,
      }}
    >
      <HeadlessInputNumber
        {...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 HeadlessInputNumberPercentage() {
  const args: React.ComponentProps<typeof HeadlessInputNumber> = {
    isPercentage: true,
    decimalPlaces: 2,
    suffix: '%',
    placeholder: 'Type 50 → actual is 0.5',
  };
  return <ControlledWrapper {...args} />;
}
```

### Negative values
Allow negative input and compare intermediate editing states with complete values.
```tsx preview
import { useState } from 'react';

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

function ControlledWrapper(
  props: React.ComponentProps<typeof HeadlessInputNumber>,
) {
  const [value, setValue] = useState((props.value as string | undefined) ?? '');
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 12,
        minWidth: 0,
        width: '100%',
        maxWidth: 320,
      }}
    >
      <HeadlessInputNumber
        {...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 HeadlessInputNumberAllowNegative() {
  const args: React.ComponentProps<typeof HeadlessInputNumber> = {
    allowNegative: true,
    placeholder: 'Type -123.45',
  };
  return <ControlledWrapper {...args} />;
}
```

### Range limits
Constrain accepted values with bounds and observe blur behavior.
```tsx preview
import { useState } from 'react';

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

function ControlledWrapper(
  props: React.ComponentProps<typeof HeadlessInputNumber>,
) {
  const [value, setValue] = useState((props.value as string | undefined) ?? '');
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 12,
        minWidth: 0,
        width: '100%',
        maxWidth: 320,
      }}
    >
      <HeadlessInputNumber
        {...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 HeadlessInputNumberClampedRange() {
  const args: React.ComponentProps<typeof HeadlessInputNumber> = {
    min: 0,
    max: 100,
    decimalPlaces: 0,
    placeholder: 'Type 999, blur to clamp to 100',
  };
  return <ControlledWrapper {...args} />;
}
```

### Pad decimals on blur
Pad decimal places to the configured precision when editing ends.
```tsx preview
import { useState } from 'react';

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

function ControlledWrapper(
  props: React.ComponentProps<typeof HeadlessInputNumber>,
) {
  const [value, setValue] = useState((props.value as string | undefined) ?? '');
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 12,
        minWidth: 0,
        width: '100%',
        maxWidth: 320,
      }}
    >
      <HeadlessInputNumber
        {...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 HeadlessInputNumberPadOnBlurAlways() {
  const args: React.ComponentProps<typeof HeadlessInputNumber> = {
    padDecimalsOnBlur: 'always',
    decimalPlaces: 2,
    placeholder: 'Type 5, blur to see 5.00',
  };
  return <ControlledWrapper {...args} />;
}
```

### Localized separators
Use a dot for grouping and a comma for decimal separation.
```tsx preview
import { useState } from 'react';

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

function ControlledWrapper(
  props: React.ComponentProps<typeof HeadlessInputNumber>,
) {
  const [value, setValue] = useState((props.value as string | undefined) ?? '');
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 12,
        minWidth: 0,
        width: '100%',
        maxWidth: 320,
      }}
    >
      <HeadlessInputNumber
        {...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 HeadlessInputNumberEuropeanLocale() {
  const args: React.ComponentProps<typeof HeadlessInputNumber> = {
    decimalSeparator: ',',
    thousandsSeparator: '.',
    decimalPlaces: 2,
    placeholder: '1.234,56',
  };
  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


### [#](#headlessinputnumber)HeadlessInputNumber



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



### [#](#numberinput)NumberInput



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

