---
name: form-numeric-input-usage
description: >
Use after component-usage-ux when an app needs @techsio/ui-kit
FormNumericInput for labeled numeric fields using NumericInput compound
children, validation status, help text, and number-specific constraints.
metadata:
component_version: "1.4.0"
type: "core"
library: "@techsio/ui-kit"
library_version: "0.3.2"
requires: "component-usage-ux numeric-input-usage app-token-overrides ux-guidelines"
resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md"
sources: "https://zagjs.com/components/react/number-input"
contributor_sources: "libs/ui/src/molecules/form-numeric-input.tsx libs/ui/src/atoms/numeric-input.tsx libs/ui/stories/molecules/form-numeric-input.stories.tsx libs/ui/src/molecules/form-numeric-input.figma.ts"
audience: "consumer"
---
> Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory.
# @techsio/ui-kit FormNumericInput Usage
Use FormNumericInput for labeled quantities, limits, prices, or measurements.
It requires NumericInput compound children.
## UX/UI guidelines
House rules come from the `ux-guidelines` skill (writing, formatting, states,
where actions and feedback live). This section applies them to `FormNumericInput`.
**Use it when**
- Labelled exact numbers: price, quantity, stock, discount %, weight, dimensions.
**Use something else when**
| Need | Use instead |
| --- | --- |
| Approximate value where feel matters (volume, price range filter) | Slider (optionally paired) |
| Identifiers that look numeric (postal code, card, order #) | FormInput with `inputMode="numeric"` |
| Unlabelled compact stepper (cart line) | NumericInput |
**Do**
- Pass the app `locale` and `formatOptions` (currency, percent, unit) so display matches the rest of the app.
- Set `min`, `max` and step; show the limits in help text when not obvious (`Up to 99 per order`).
- Put the unit in the label (`Price (€)`, `Weight (kg)`) when not formatted into the value.
- Keep increment/decrement triggers for small integer adjustments; omit them for prices.
**Don't**
- Use `` or FormInput for numbers.
- Silently clamp a typed value without telling the user — show the limit.
**Copy and states**
- Validation: `Enter a quantity between 1 and 99.` with formatted numbers.
**Behaviour (from the UX spec)**
- Never replace an empty draft with `0` or the minimum; clearing to retype must not snap back to the old number.
- Over a bound, keep the typed number and state the range; pass `clampValueOnBlur={false}` when the out-of-range draft must stay visible.
- A stepper blocked at a bound is not a disabled field.
**Figma → code**
| Figma | Code |
| --- | --- |
| `state=error` / `success` / `warning` | `validateStatus` |
| `state=disabled` | `disabled` |
| `state=readonly` | `readOnly` (steppers hidden) |
| `required=true` | `required` |
Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Molecules/FormNumericInput → UX guidelines*.
## Setup
```tsx
```
Supported props:
```text
id: optional (stable unique ID generated when omitted or empty)
label: ReactNode
children: NumericInput compound parts
validateStatus: default | error | success | warning
helpText, showHelpTextIcon
requiredLabel: screen-reader text for the required state; pass a translation, "" omits it (default "(required)")
NumericInputProps excluding children
```
## Core Patterns
### Keep NumericInput anatomy inside
Do not pass plain `` or native buttons as children. Use NumericInput
parts.
### Express domain constraints with props
Use `min`, `max` and `step` for bounds/stepping, and `precision` and `locale`
for presentation, not custom blur parsing. Integer-only business rules still
require explicit app validation; formatting is not validation.
### Use validateStatus for errors
FormNumericInput forwards all validation states to NumericInput. Error sets
`invalid`; success/warning retain their status borders without `aria-invalid`.
Explicit `invalid` takes precedence, and disabled visuals remain authoritative.
## Common Mistakes
### HIGH Missing NumericInput children
Wrong:
```tsx
```
Correct:
```tsx
```
Source: libs/ui/src/molecules/form-numeric-input.tsx
### HIGH Native number field
Wrong:
```tsx
```
Correct:
```tsx
```
Source: libs/ui/src/atoms/numeric-input.tsx
### Controlled string drafts
String values are supported when the parent must preserve empty or rejected
drafts. Use onValueChange for text updates; the legacy onChange still receives
a number (or NaN when cleared). Numeric values provide immediate formatting.
```tsx
const [draft, setDraft] = useState("1")
setDraft(value)}
min={1}
max={10}
clampValueOnBlur={false}
>
```
Use `clampValueOnBlur={false}` to retain out-of-range drafts; validate the
nonempty, finite, in-range number before saving. Blur/Enter commit callbacks do
not save automatically.
## Validation Commands
```sh
rg -U -P -n "type=\"number\"|]*label=)" apps
rg -n "]*className=.*(border-|text-|px-|py-|gap-)" apps
```
## Read-only and feedback contracts
Use `readOnly` for visible, focusable, copyable values that must not change.
The value keeps full contrast and a subtle surface; disabled wins when both
are set. Canonical sizes are sm/md/lg, default md, including labels and feedback.
`helpText` renders StatusText with a stable unique ID, merged with caller
`aria-describedby`. Errors also set `aria-invalid` and `aria-errormessage`;
the internally generated error reference disappears when wrapper validation clears. Error/warning/success
icons always remain enabled; `showHelpTextIcon` only customizes neutral help.
Validate on blur/submit and use actionable copy rather than color alone.
Caller-supplied `aria-errormessage` IDs are preserved independently of
`validateStatus`, including when the caller supplies the invalid state. Clear
caller-owned error IDs and invalid state together when removing that message;
the wrapper only manages the lifecycle of its own generated error reference.
## Silent native form reset
Native form reset calls no value-change callbacks and dispatches no native
`input` or `change` events. Uncontrolled controls silently restore their default;
controlled controls keep the latest parent value and re-sync visible text, native
value and FormData. Handle the form's `onReset` to intentionally change parent
state. Canceled resets change nothing. React's value tracker is re-synced after
restoration, so the next identical user edit notifies exactly once. Reset does
not move focus.
## Draft and native-handler ownership
The NumericInput children retain composed native event handlers: observation
does not replace machine typing/blur behavior, and `preventDefault()` cancels the
matching action. Blur commits report the clamped value. Zero precision and
`step={1}` do not validate whole-unit quantities; keep fractional drafts visible
and validate nonempty, finite integer values in the app before saving.