NumberBox

17:06

Description

Increments/decrements a value: tap the +/- buttons or type directly, with the value two-way bound via v-model. Supports a step size, min / max range limits and long-press continuous change; positive-integer restricts input to positive integers by default.

Compatibility

Platform	Support
App	✅ Supported
H5	✅ Supported
WeChat Mini Program	✅ Supported

Examples

Basic Usage

Bind value via v-model; modify by tapping +/- or manual input.

View source

<template>
    <ux-number-box v-model="val" />
</template>

<script setup lang="uts">
const val = ref<number>(1);
</script>

Step Size

Set the increment/decrement via the step prop; here it is 10.

View source

<template>
    <ux-number-box v-model="val" :step="10" />
</template>

<script setup lang="uts">
const val = ref<number>(10);
</script>

Range Limit

Limit min and max values via min and max props; here 5-50.

View source

<template>
    <ux-number-box v-model="val" :min="5" :max="50" />
</template>

<script setup lang="uts">
const val = ref<number>(5);
</script>

Disabled

When disabled=true, all operations are disabled.

View source

<template>
    <ux-number-box v-model="val" :disabled="true" />
</template>

<script setup lang="uts">
const val = ref<number>(1);
</script>

Custom Size

Customize size via size, input-width, input-height props.

View source

<template>
    <ux-number-box v-model="val" :size="15" :input-width="60" :input-height="30" />
</template>

<script setup lang="uts">
const val = ref<number>(1);
</script>

API

Props

Property	Description	Type	Default	Version
customStyle	Custom root element style	UTSJSONObject	-	-
customClass	Custom root element style class	string	''	-
modelValue	Initial input value (default 1)	number	1	-
bgColor	Background color of the input and buttons	string	''	-
min	Minimum value the user can enter (default 0)	number	0	-
max	Maximum value the user can enter (default 50000)	number	99999	-
step	Step size added or subtracted each time (default 1)	number	1	-
disabled	Whether to disable all operations (default false)	boolean	false	-
size	Font size of the input text and buttons, in px (default 13)	number | string	13	-
color	Color of the input text and the +/- icons	string	''	-
inputWidth	Input width in px (default 40)	number | string	40	-
inputHeight	Height of the input and buttons in px (default 25)	number | string	25	-
index	Distinguishes which input changed in event callbacks	number | string	''	-
disabledInput	Whether to forbid manual typing in the input (default false)	boolean	false	-
cursorSpacing	Distance between the cursor and the keyboard (default 50)	number | string	100	-
longPress	Whether to enable long-press continuous increment/decrement (default true)	boolean	true	-
pressTime	Interval between repeats after a long press starts, in ms (default 125)	number | string	250	-
positiveInteger	Whether only positive integers can be entered (default true)	boolean	true	-
validateState	Validation error state; turns the border red on error	boolean	false	-

Events

Event	Description	Params	Version
change	Fires when the input content changes	value: UTSJSONObject	-
blur	Fires when the input loses focus	value: UTSJSONObject	-
focus	Fires when the input gains focus	-	-
minus	Fires when the minus button is tapped	value: UTSJSONObject	-
plus	Fires when the plus button is tapped	value: UTSJSONObject	-

Slots

ux-number-box has no slots.

Notes

• Manual input accepts non-negative integers only: on blur the value is checked with /^\d+$/, and input containing a decimal point, a minus sign or a leading zero is reset to min, then clamped to min / max.
• positive-integer (default true) blocks negative numbers and decimals while typing, falling back to the last valid value.
• Tapping +/- so the result would exceed min / max does not update the value (the tap is ignored); at a boundary or when disabled, the button is shown grayed out.
• long-press is enabled by default: holding a +/- button repeats every press-time (default 250ms) and stops on release.
• disabled-input only forbids manual typing; the +/- buttons still work. disabled disables everything (input and buttons).
• The component can inject the ux-form-item context: value changes and blur trigger its validation, and validate-state or a failed form validation adds a red border on the root.