Components/NumberInput

NumberInput

A numeric field with step buttons, clamping, and precision.

VerifiedSince 0.3.7

Usage

Range and Precision

min / max set the range, step the increment, and precision the decimal places.

Loading demo...

Best Practices

  • Pass explicit min, max, and step for percentages, quotas, and pagination.
  • Handle decimals with precision instead of rounding in the consumer after every event.
  • Set controls=false in dense table filters, where typing is faster.
  • Treat null as unset in validation and API mapping.

Edge and States

The steppers sit inside the same inset ring with concentric outer corners, and state colours match the input.

Loading demo...

API Reference

Props

PropTypeDefaultDescription
modelValuenumber | nullnullThe number; null when the field is empty, bound with v-model.
minnumber-Minimum value.
maxnumber-Maximum value.
stepnumber1Increment of the step buttons and the native input.
precisionnumber-Decimal places to keep.
placeholderstring''Placeholder text.
disabledbooleanfalseDisables the field and the buttons.
readonlybooleanfalseMakes the field read-only and blocks stepping.
controlsbooleantrueShows the decrease and increase buttons.
decreaseLabelstring'Decrease value'The decrease button's aria-label; pass a localized string.
increaseLabelstring'Increase value'The increase button's aria-label; pass a localized string.

Events

EventParamsDescription
update:modelValue(value: number | null)Fires with the normalized value.
change(value: number | null)Fires together with update:modelValue.
focus(event: FocusEvent)The native focus event.
blur(event: FocusEvent)The native blur event; the field re-normalizes on blur.

Exposed Methods

NameDescription
focus()Focuses the native input.
blur()Blurs the native input.
inputRefRef to the native input.

Overview

  • Empty input normalizes to null.
  • Typed values clamp to min / max on blur, step results right away; precision rounds after clamping.
  • Unparseable text left at blur falls back to the current value, or null if there is none.
  • controls=false hides the step buttons and keeps the native numeric field.
  • readonly and disabled both block stepping; disabled also disables the field.
  • Inside a TxFormItem it takes the id, aria-describedby, aria-invalid and required, and draws a red edge while the item shows an error; the form's disabled applies too and blocks stepping.

Technologies

  • Attrs other than class / style go to the native input.
  • Source: packages/tuffex/packages/components/src/number-input/.
查看源码
packages/tuffex/packages/components/src/number-input/index.ts