# NumberInput

Source: /tuil/docs/reference/components/forms/number-input
Locale: en

NumberInput component API, behavior, and executable example.





{/* Generated by tooling/docs/generate-reference.ts. */}

<PublishedStory storyId="component-acceptance" variant="Field" />

## API and events [#api-and-events]

Connect semantic terminal controls to typed form state, validation, descriptions, errors, hints, and submission.

```tsx
export function NumberInput({
  value,
  defaultValue = 0,
  onValueChange,
  field: adaptedField,
  validators,
  min = Number.NEGATIVE_INFINITY,
  max = Number.POSITIVE_INFINITY,
  step = 1,
  ...props
}: NumberInputProps): ReactNode;
```

### Props, functions, and events [#props-functions-and-events]

| Member           | Type                                                                             | Required | Description                                                                                                             | Related types                                                                       |
| ---------------- | -------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `field`          | `AdaptedTanStackField<number> \| undefined`                                      | No       | The `field` member uses the `AdaptedTanStackField<number> \| undefined` contract.                                       | [`AdaptedTanStackField`](/tuil/docs/reference/packages/form/api/adapted-tan-stack-field) |
| `validators`     | `FieldValidators<number> \| undefined`                                           | No       | The `validators` member uses the `FieldValidators<number> \| undefined` contract.                                       | [`FieldValidators`](/tuil/docs/reference/packages/form/api/field-validators)             |
| `value`          | `number \| undefined`                                                            | No       | The `value` member uses the `number \| undefined` contract.                                                             | —                                                                                   |
| `defaultValue`   | `number \| undefined`                                                            | No       | The `defaultValue` member uses the `number \| undefined` contract.                                                      | —                                                                                   |
| `onValueChange`  | `((value: number) => void \| Promise<void>) \| undefined`                        | No       | The `onValueChange` member uses the `((value: number) => void \| Promise<void>) \| undefined` contract.                 | —                                                                                   |
| `min`            | `number \| undefined`                                                            | No       | The `min` member uses the `number \| undefined` contract.                                                               | —                                                                                   |
| `max`            | `number \| undefined`                                                            | No       | The `max` member uses the `number \| undefined` contract.                                                               | —                                                                                   |
| `step`           | `number \| undefined`                                                            | No       | The `step` member uses the `number \| undefined` contract.                                                              | —                                                                                   |
| `placeholder`    | `string \| undefined`                                                            | No       | The `placeholder` member uses the `string \| undefined` contract.                                                       | —                                                                                   |
| `autoFocus`      | `boolean \| undefined`                                                           | No       | The `autoFocus` member uses the `boolean \| undefined` contract.                                                        | —                                                                                   |
| `variant`        | `string \| undefined`                                                            | No       | The `variant` member uses the `string \| undefined` contract.                                                           | —                                                                                   |
| `size`           | `"sm" \| "md" \| "lg" \| undefined`                                              | No       | The `size` member uses the `"sm" \| "md" \| "lg" \| undefined` contract.                                                | —                                                                                   |
| `unstyled`       | `boolean \| undefined`                                                           | No       | The `unstyled` member uses the `boolean \| undefined` contract.                                                         | —                                                                                   |
| `className`      | `string \| undefined`                                                            | No       | The `className` member uses the `string \| undefined` contract.                                                         | —                                                                                   |
| `layout`         | `Partial<Omit<LayoutNodeInput, "id" \| "children" \| "semantics">> \| undefined` | No       | The `layout` member uses the `Partial<Omit<LayoutNodeInput, "id" \| "children" \| "semantics">> \| undefined` contract. | —                                                                                   |
| `id`             | `string \| undefined`                                                            | No       | The `id` member uses the `string \| undefined` contract.                                                                | —                                                                                   |
| `testId`         | `string \| undefined`                                                            | No       | The `testId` member uses the `string \| undefined` contract.                                                            | —                                                                                   |
| `role`           | `SemanticRole \| undefined`                                                      | No       | The `role` member uses the `SemanticRole \| undefined` contract.                                                        | [`SemanticRole`](/tuil/docs/reference/packages/core/api/semantic-role)                   |
| `label`          | `string \| undefined`                                                            | No       | The `label` member uses the `string \| undefined` contract.                                                             | —                                                                                   |
| `description`    | `string \| undefined`                                                            | No       | The `description` member uses the `string \| undefined` contract.                                                       | —                                                                                   |
| `disabled`       | `boolean \| undefined`                                                           | No       | The `disabled` member uses the `boolean \| undefined` contract.                                                         | —                                                                                   |
| `readOnly`       | `boolean \| undefined`                                                           | No       | The `readOnly` member uses the `boolean \| undefined` contract.                                                         | —                                                                                   |
| `selected`       | `boolean \| undefined`                                                           | No       | The `selected` member uses the `boolean \| undefined` contract.                                                         | —                                                                                   |
| `checked`        | `boolean \| undefined`                                                           | No       | The `checked` member uses the `boolean \| undefined` contract.                                                          | —                                                                                   |
| `expanded`       | `boolean \| undefined`                                                           | No       | The `expanded` member uses the `boolean \| undefined` contract.                                                         | —                                                                                   |
| `valueText`      | `string \| undefined`                                                            | No       | The `valueText` member uses the `string \| undefined` contract.                                                         | —                                                                                   |
| `mask`           | `string \| undefined`                                                            | No       | The `mask` member uses the `string \| undefined` contract.                                                              | —                                                                                   |
| `session`        | `EditorSession \| undefined`                                                     | No       | The `session` member uses the `EditorSession \| undefined` contract.                                                    | [`EditorSession`](/tuil/docs/reference/packages/editor/api/editor-session)               |
| `editorProvider` | `EditorProvider \| undefined`                                                    | No       | The `editorProvider` member uses the `EditorProvider \| undefined` contract.                                            | [`EditorProvider`](/tuil/docs/reference/packages/editor/api/editor-provider)             |
| `clipboard`      | `EditorClipboardAdapter \| undefined`                                            | No       | The `clipboard` member uses the `EditorClipboardAdapter \| undefined` contract.                                         | —                                                                                   |
| `documentType`   | `string \| undefined`                                                            | No       | The `documentType` member uses the `string \| undefined` contract.                                                      | —                                                                                   |
| `onSubmit`       | `((value: string) => void \| Promise<void>) \| undefined`                        | No       | The `onSubmit` member uses the `((value: string) => void \| Promise<void>) \| undefined` contract.                      | —                                                                                   |
| `onBlur`         | `(() => void \| Promise<void>) \| undefined`                                     | No       | The `onBlur` member uses the `(() => void \| Promise<void>) \| undefined` contract.                                     | —                                                                                   |
| `focusOrder`     | `number \| undefined`                                                            | No       | The `focusOrder` member uses the `number \| undefined` contract.                                                        | —                                                                                   |
| `maxLength`      | `number \| undefined`                                                            | No       | The `maxLength` member uses the `number \| undefined` contract.                                                         | —                                                                                   |
| `onArrowUp`      | `(() => void \| Promise<void>) \| undefined`                                     | No       | The `onArrowUp` member uses the `(() => void \| Promise<void>) \| undefined` contract.                                  | —                                                                                   |
| `onArrowDown`    | `(() => void \| Promise<void>) \| undefined`                                     | No       | The `onArrowDown` member uses the `(() => void \| Promise<void>) \| undefined` contract.                                | —                                                                                   |

Controls expose `onValueChange`, `onSubmit`, focus, selection, and validation callbacks.

Callback props run after the documented input is accepted. Callbacks are not cancellable unless their return type or description states otherwise.

## Interaction and capabilities [#interaction-and-capabilities]

Text controls edit directly; choice controls use arrows and Space or Enter; `Form` coordinates validation and submission.

The published manifest records keyboard, focus, pointer, theme, terminal, semantic, event, and dependency requirements.

## Complete import [#complete-import]

```tsx
import { NumberInput } from "@/components/tuil/forms/controls";
```