--- name: numeric-input-usage description: > Use after component-usage-ux when an app needs @techsio/ui-kit NumericInput for accessible number entry with Zag.js spinbutton behavior, compound parts, numeric compatibility or controlled string drafts, locale formatting, min/max/step, and token-first styling. metadata: component_version: "2.0.0" type: "core" library: "@techsio/ui-kit" library_version: "0.3.2" requires: "component-usage-ux zag-compound-components 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/atoms/numeric-input.tsx libs/ui/src/tokens/components/atoms/_numeric-input.css libs/ui/stories/atoms/numeric-input.stories.tsx libs/ui/src/atoms/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 NumericInput Usage Use NumericInput for quantities, percentages, currency-like values, or bounded numbers where keyboard, wheel, increment/decrement, and validation behavior matter. ## UX/UI guidelines House rules come from the `ux-guidelines` skill (writing, formatting, states, where actions and feedback live). This section applies them to `NumericInput`. **Use it when** - Bare numeric controls in compact compositions: cart quantity, inline table editors, stepper fields. **Use something else when** | Need | Use instead | | --- | --- | | A labelled numeric field | FormNumericInput | | Quantity with a visible unit, helper/error and pending updates | QuantityField (quantity-field-usage) | | Approximate values | Slider | | Numeric identifiers | Input | **Do** - Pass the app `locale` — the component defaults to `cs-CZ` (ux-guidelines/formatting#locale-defaults-in-the-kit). - Use `formatOptions` for currency/percent/unit so the displayed value matches the rest of the UI. - Set `min`/`max`/`step`; at the limit, disable only the trigger that would exceed it. - Right-align numeric editors inside numeric table columns. **Don't** - Use `type="number"` inputs. - Clamp silently on blur without feedback. **Copy and states** - Trigger labels `Increase quantity` / `Decrease quantity`. **Behaviour (from the UX spec)** - Empty, zero and invalid are different; never turn an empty draft into `0` or the minimum. - Default `clampValueOnBlur` clamps out-of-range values on blur; pass `false` and explain the range when the user must fix the value. - Decrementing to zero never removes a line item; removal is its own action. - The steppers' default accessible names are Zag's English `increment value` / `decrease value`; pass localized `aria-label`s. **Figma → code** | Figma | Code | | --- | --- | | `state=error` | `validateStatus="error"` or `invalid` | | `state=disabled` | `disabled` | | `state=readonly` | `readOnly` (steppers hidden) | | — (not in Figma) | `validateStatus="success" \| "warning"` | Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Atoms/NumericInput → UX guidelines*. ## Setup ```tsx import { NumericInput } from "@techsio/ui-kit/atoms/numeric-input" ``` Public wrapper props support both existing numbers and Zag text drafts: ```text value/defaultValue: number | string onChange: (value: number) => void (legacy; clearing can emit NaN) onValueChange: (details: NumberInput.ValueChangeDetails) => void onValueCommit / onValueInvalid / onFocusChange: Zag callbacks size: sm | md | lg locale: string, default cs-CZ precision, min, max, step, name, disabled, required, invalid allowMouseWheel, allowOverflow, clampValueOnBlur, spinOnPress, formatOptions ``` Pass native input attributes such as `autoFocus`, `aria-label` and `aria-labelledby` to `NumericInput.Input`. Automatic focus is synchronized with Zag so typing and arrow keys work immediately after mount. `NumericInputTemplate` forwards its own `aria-label` / `aria-labelledby` to the input (not the root), so an unlabelled template still has a name: ``. ## Core Patterns ### Keep the compound anatomy intact ```tsx ``` Do not replace trigger parts with native buttons. The subcomponents spread Zag part props and use Button/Input tokens. ### Respect wrapper value types Existing numeric values keep their formatting and `onChange(valueAsNumber)` contract. Clearing a numeric field can emit NaN; existing consumers may normalize that to undefined. Do not use NaN as a controlled text draft. For editable drafts, keep `value` as a string and update it from `onValueChange(details.value)`. String values pass directly to Zag; an explicit parent update remains authoritative. `onValueCommit` reports Zag blur/Enter confirmation and does not persist anything by itself. ```tsx const [quantity, setQuantity] = useState(1) ``` ### Use locale and precision deliberately ```tsx ``` Use `formatOptions` for localized decimal parsing as well as display options. Locale alone is not sufficient to assume comma parsing. For editable decimals, set an appropriate maximumFractionDigits and verify the parsed value. Currency and percent formats need extra care to remain usable input values. Existing NumericInput defaults retain clampValueOnBlur=true. To keep a typed out-of-range draft, pass clampValueOnBlur=false. Keep allowOverflow=false when steppers must respect the bounds; allowOverflow=true also enables stepping beyond them. Zag may normalize incomplete fragments at blur/Enter. ### Use describedBy for external help/error text ```tsx ``` `describedBy` is merged into the input `aria-describedby`. When `id` is provided, it is also the native input's ID, so labels and form error summary links can target the editable field. ## Input refs and cancellation-safe native reset `NumericInput` root `ref` targets its container. For imperative focus use `NumericInput.Input ref?: Ref`; this is the editable native spinbutton. React 19 callback disposers/object-ref clearing work in controlled and uncontrolled modes. Keep machine focus/blur behaviour intact when observing input events. ```tsx import { useId, useRef, useState } from "react" import { Label } from "@techsio/ui-kit/atoms/label" import { NumericInput } from "@techsio/ui-kit/atoms/numeric-input" function OrderQuantity() { const id = useId() const input = useRef(null) const [draft, setDraft] = useState("2") return setDraft(value)} min={1}> } ``` Keep controlled drafts in app state; rejected edits restore the prop value, not just the next blur's value. Native owner reset tracks the input's actual form association, including reassociation/ID changes. A canceled native or React reset leaves the draft untouched. Accepted uncontrolled reset restores the initial default after cancellation has settled, without simulated clicks or focus transfer. Controlled reset needs an explicit app-state update. Native nested disabled fieldsets and first-legend exceptions apply to the input and steppers; read-only retains focus/copy/submission. Ref/subscription cleanup must not leave reset work acting on a removed input. ## Common Mistakes ### HIGH Losing a controlled draft through numeric conversion Wrong for a draft that must remain empty or partially entered: ```tsx setDraft(String(value))} /> ``` Correct: ```tsx const [draft, setDraft] = useState("10") setDraft(value)} clampValueOnBlur={false} > ``` Legacy numeric callers can continue with `value={quantity}` and `onChange`. Both callback forms may coexist; each receives its own contract once per Zag change. Do not have both handlers independently overwrite the same draft. Source: libs/ui/src/atoms/numeric-input.tsx ### HIGH Custom steppers Wrong: ```tsx ``` Correct: ```tsx ``` Source: https://zagjs.com/components/react/number-input ### HIGH Inline sizing/color classes Wrong: ```tsx ``` Correct: ```tsx ``` Source: libs/ui/src/tokens/components/atoms/_numeric-input.css ### MEDIUM Missing min/max semantics Wrong: ```tsx ``` Correct for a quantity: ```tsx ``` Use min/max/step to express domain constraints, not custom blur handlers. ## Validation Commands ```sh rg -n ']*type="number"' apps rg -U -P -n "]*className=.*(bg-|text-|border-|px-|py-)" apps rg -U -P -n " ...)` and validate before committing. ## 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. ## Native handlers and integer quantities Handlers on `NumericInput.Input` compose with the machine. Observational handlers retain typing, blur clamping and commit behavior; `preventDefault()` cancels the corresponding native action. `onValueCommit` reports the clamped blur value, not the preceding out-of-bounds draft. A rejected controlled edit restores the latest parent value even if the parent does not render again. `precision={0}`, `maximumFractionDigits: 0` and `step={1}` are not integer-domain validation. Fractional typed drafts remain visible for correction instead of being silently rounded. Before submitting whole-unit quantities, require a nonempty draft, `Number.isFinite(valueAsNumber)`, `Number.isInteger(valueAsNumber)` and the product's bounds. Reject fractions with actionable feedback; do not use `parseInt`, truncate the draft or rely on display formatting as consent. Native edits are captured synchronously and deferred DOM writes are tied to the edit that scheduled them, so a stale blur commit or a late controlled acknowledgement can never overwrite newer typing. External replacement, silent reset, refusal and blur normalization stay authoritative. Keep custom input ids in sync with the stepper and focus references. Controlled values are acknowledged or refused by numeric value: decimal drafts such as 1. and 1.50 are never rewritten, while a parent that keeps its previous value restores it on screen and in the submitted value, including after an earlier accepted edit.