# @fayegram-ai/faye-ui/controls/number-field

Public exports and dependency-resolved component properties, with usage and rendering guidance.

## Import

```tsx
import { NumberField } from '@fayegram-ai/faye-ui/controls/number-field';
```

[Usage and behavior guide](/docs/numeric/) · [API JSON](/api/packages/controls/number-field.json)

This entry declares a client boundary. Follow the rendering guide for framework integration.

## Public exports

| Name | Kind | Resolved declaration type |
|---|---|---|
| `NumberField` | value | `{ readonly Root: typeof Root; readonly Group: { (input: Omit<import("@base-ui/react").NumberFieldGroupProps, "ref"> & import("react").RefAttributes<HTMLDivElement> & { variants?: { readonly size?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"number-field", "size"> \| undefined; readonly tone?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"number-field", "tone"> \| undefined; } \| undefined; }): import("react").ReactElement; displayName: string; }; readonly Input: { (input: Omit<import("@base-ui/react").NumberFieldInputProps, "ref"> & import("react").RefAttributes<HTMLInputElement> & { variants?: { readonly size?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"number-field", "size"> \| undefined; readonly tone?: impor… (full type in API JSON)` |

## NumberField

Public component; use the linked family guide for complete composition and behavior.

Dependency-resolved declaration properties. Common React/native HTML attributes are omitted from the table; use the full declaration and React/native references. Generic and union restrictions remain authoritative in TypeScript.

### NumberField.Root

| Property | Required | Type | Meaning |
|---|---|---|---|
| `allowOutOfRange` | No | `boolean \| undefined` | When true, direct text entry may be outside the `min`/`max` range without clamping, so native range underflow/overflow validation can occur. Step-based interactions (keyboard arrows, buttons, wheel, scrub) still clamp. |
| `allowWheelScrub` | No | `boolean \| undefined` | Whether to allow the user to scrub the input value with the mouse wheel while focused and hovering over the input. |
| `className` | No | `string \| ((state: NumberFieldRootState) => string \| undefined) \| undefined` | CSS class applied to the element, or a function that returns a class based on the component's state. |
| `defaultValue` | No | `number \| undefined` | The uncontrolled value of the field when it's initially rendered. To render a controlled number field, use the `value` prop instead. |
| `disabled` | No | `boolean \| undefined` | Whether the component should ignore user interaction. |
| `form` | No | `string \| undefined` | Identifies the form that owns the hidden input. Useful when the number field is rendered outside the form. |
| `format` | No | `Intl.NumberFormatOptions \| undefined` | Options to format the input value. |
| `id` | No | `string \| undefined` | The id of the input element. |
| `inputRef` | No | `Ref<HTMLInputElement> \| undefined` | A ref to access the hidden input element. |
| `largeStep` | No | `number \| undefined` | The large step value of the input element when incrementing while the shift key is held. Snaps to multiples of this value when `snapOnStep` is enabled. |
| `locale` | No | `Intl.LocalesArgument` | The locale of the input element. Defaults to the user's runtime locale. |
| `max` | No | `number \| undefined` | The maximum value of the input element. |
| `min` | No | `number \| undefined` | The minimum value of the input element. |
| `name` | No | `string \| undefined` | Identifies the field when a form is submitted. |
| `onValueChange` | No | `((value: number \| null, eventDetails: Base.Root.ChangeEventDetails) => void) \| undefined` | Callback fired when the number value changes. The `eventDetails.reason` indicates what triggered the change: - `'input-change'` for parseable typing or programmatic text updates - `'input-clear'` when the field becomes empty - `'input-blur'` when formatting (and clamping, if enabled) occurs on blur - `'input-paste'` for paste interactions - `'keyboard'` for arrow-key/Home/End stepping (typing digits uses `'input-change'`/`'input-clear'`) - `'increment-press'` / `'decrement-press'` for button presses on the increment and decrement controls - `'wheel'` for wheel-based scrubbing - `'scrub'` for scrub area drags |
| `onValueCommitted` | No | `((value: number \| null, eventDetails: Base.Root.CommitEventDetails) => void) \| undefined` | Callback function that is fired when the value is committed. It runs later than `onValueChange`, when: - The input is blurred after typing a value. - The pointer is released after scrubbing or pressing the increment/decrement buttons. It runs simultaneously with `onValueChange` when interacting with the keyboard or the mouse wheel. **Warning**: This is a generic event not a change event. |
| `readOnly` | No | `boolean \| undefined` | Whether the user should be unable to change the field value. |
| `render` | No | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, NumberFieldRootState> \| undefined` | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| `required` | No | `boolean \| undefined` | Whether the user must enter a value before submitting a form. |
| `smallStep` | No | `number \| undefined` | The small step value of the input element when incrementing while the alt key is held. Snaps to multiples of this value when `snapOnStep` is enabled. |
| `snapOnStep` | No | `boolean \| undefined` | Whether the value should snap to the nearest step when incrementing or decrementing. |
| `step` | No | `number \| "any" \| undefined` | Amount to increment and decrement with the buttons and arrow keys, or to scrub with pointer movement in the scrub area. To always enable step validation on form submission, specify the `min` prop explicitly in conjunction with this prop. Specify `step="any"` to always disable step validation; interactive stepping then uses a base amount of `1`, while the alt and shift keys still step by `smallStep` and `largeStep`. |
| `style` | No | `CSSProperties \| ((state: NumberFieldRootState) => React.CSSProperties \| undefined) \| undefined` | Style applied to the element, or a function that returns a style object based on the component's state. |
| `value` | No | `number \| null \| undefined` | The raw numeric value of the field. |

### NumberField.Group

| Property | Required | Type | Meaning |
|---|---|---|---|
| `className` | No | `string \| ((state: NumberFieldGroupState) => string \| undefined) \| undefined` | CSS class applied to the element, or a function that returns a class based on the component's state. |
| `render` | No | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, NumberFieldGroupState> \| undefined` | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| `style` | No | `CSSProperties \| ((state: NumberFieldGroupState) => React.CSSProperties \| undefined) \| undefined` | Style applied to the element, or a function that returns a style object based on the component's state. |
| `variants` | No | `{ readonly size?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"number-field", "size"> \| undefined; readonly tone?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"number-field", "tone"> \| undefined; } \| undefined` | See the usage contract and declaration. |

### NumberField.Input

| Property | Required | Type | Meaning |
|---|---|---|---|
| `aria-roledescription` | No | `string \| undefined` | A user-friendly description of the input's role for assistive tech. This is a role description, not an accessible name — use `Field.Label` or `aria-label` to name the control. |
| `className` | No | `string \| ((state: NumberFieldInputState) => string \| undefined) \| undefined` | CSS class applied to the element, or a function that returns a class based on the component's state. |
| `render` | No | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, NumberFieldInputState> \| undefined` | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| `style` | No | `CSSProperties \| ((state: NumberFieldInputState) => React.CSSProperties \| undefined) \| undefined` | Style applied to the element, or a function that returns a style object based on the component's state. |
| `variants` | No | `{ readonly size?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"number-field", "size"> \| undefined; readonly tone?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"number-field", "tone"> \| undefined; } \| undefined` | See the usage contract and declaration. |

### NumberField.Increment

| Property | Required | Type | Meaning |
|---|---|---|---|
| `className` | No | `string \| ((state: NumberFieldIncrementState) => string \| undefined) \| undefined` | CSS class applied to the element, or a function that returns a class based on the component's state. |
| `nativeButton` | No | `boolean \| undefined` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |
| `render` | No | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, NumberFieldIncrementState> \| undefined` | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| `style` | No | `CSSProperties \| ((state: NumberFieldIncrementState) => React.CSSProperties \| undefined) \| undefined` | Style applied to the element, or a function that returns a style object based on the component's state. |
| `variants` | No | `{ readonly size?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"number-field", "size"> \| undefined; readonly tone?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"number-field", "tone"> \| undefined; } \| undefined` | See the usage contract and declaration. |

### NumberField.Decrement

| Property | Required | Type | Meaning |
|---|---|---|---|
| `className` | No | `string \| ((state: NumberFieldDecrementState) => string \| undefined) \| undefined` | CSS class applied to the element, or a function that returns a class based on the component's state. |
| `nativeButton` | No | `boolean \| undefined` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |
| `render` | No | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, NumberFieldDecrementState> \| undefined` | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| `style` | No | `CSSProperties \| ((state: NumberFieldDecrementState) => React.CSSProperties \| undefined) \| undefined` | Style applied to the element, or a function that returns a style object based on the component's state. |
| `variants` | No | `{ readonly size?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"number-field", "size"> \| undefined; readonly tone?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"number-field", "tone"> \| undefined; } \| undefined` | See the usage contract and declaration. |

### NumberField.ScrubArea

| Property | Required | Type | Meaning |
|---|---|---|---|
| `className` | No | `string \| ((state: NumberFieldScrubAreaState) => string \| undefined) \| undefined` | CSS class applied to the element, or a function that returns a class based on the component's state. |
| `direction` | No | `"horizontal" \| "vertical" \| undefined` | Cursor movement direction in the scrub area. |
| `pixelSensitivity` | No | `number \| undefined` | Determines how many pixels the cursor must move before the value changes. A higher value will make scrubbing less sensitive. |
| `render` | No | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, NumberFieldScrubAreaState> \| undefined` | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| `style` | No | `CSSProperties \| ((state: NumberFieldScrubAreaState) => React.CSSProperties \| undefined) \| undefined` | Style applied to the element, or a function that returns a style object based on the component's state. |
| `teleportDistance` | No | `number \| undefined` | If specified, determines the distance that the cursor may move from the center of the scrub area before it will loop back around. |
| `variants` | No | `{ readonly size?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"number-field", "size"> \| undefined; readonly tone?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"number-field", "tone"> \| undefined; } \| undefined` | See the usage contract and declaration. |

### NumberField.ScrubAreaCursor

| Property | Required | Type | Meaning |
|---|---|---|---|
| `className` | No | `string \| ((state: NumberFieldScrubAreaCursorState) => string \| undefined) \| undefined` | CSS class applied to the element, or a function that returns a class based on the component's state. |
| `render` | No | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, NumberFieldScrubAreaCursorState> \| undefined` | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| `style` | No | `CSSProperties \| ((state: NumberFieldScrubAreaCursorState) => React.CSSProperties \| undefined) \| undefined` | Style applied to the element, or a function that returns a style object based on the component's state. |
| `variants` | No | `{ readonly size?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"number-field", "size"> \| undefined; readonly tone?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"number-field", "tone"> \| undefined; } \| undefined` | See the usage contract and declaration. |

## Defaults and customization

Descriptor defaults: `{"size":"md","tone":"neutral"}`. Parts: `root`, `group`, `input`, `increment`, `decrement`, `scrub-area`, `scrub-area-cursor`. Explicit instance props take precedence over configured defaults.

Use semantic tokens, public part hooks and customization sheets. Keep visual configuration separate from application state.

## State, events and accessibility

For interactive controls, pair a controlled value/open prop with its corresponding change callback; default props initialize uncontrolled state. Keep application validation and submission policy explicit. Name controls with visible labels, name icon-only actions on the button, and preserve focus and dismissal behavior when replacing parts. Use native form names and submit/reset types where supported. See the usage guide for component-specific behavior and live examples.

## Declaration authority

Generated from `packages/faye-ui/dist/controls/number-field.d.ts` after the semantic package build. Common native/React attributes are intentionally omitted from property tables. Generic overloads, discriminated unions and complete inherited attributes remain authoritative in installed TypeScript declarations. [React DOM attributes](https://react.dev/reference/react-dom/components/common) and [Base UI component contracts](https://base-ui.com/react/overview/quick-start) describe the inherited foundations.