NumberInput

A text input for numeric values, with built-in long-press continuous scrolling logic for the increment/decrement buttons, and support for min, max, and precision step adjustments.

Demo

Preview

双侧分立式

右侧堆叠式

机械音效（sound）

步进点击时播放机械咔哒声（首次交互后生效）

Installation

pnpm dlx brutx-vue@latest add number-input

Usage

<script setup>
import { ref } from 'vue'
import { NumberInput } from 'brutx-ui-vue'

const count = ref(5)
</script>

<template>
    <NumberInput v-model="count" :min="0" :max="10" :step="1" />
</template>

Variants

NumberInput provides two button layout modes, configured via the layout prop:

Layout Prop	Description
split (default)	Split sides: Minus button on the left, plus button on the right, with a bold symmetrical feel.
stacked	Right-stacked: Increment/decrement buttons stacked vertically on the right.

<template>
    <!-- Split layout -->
    <NumberInput v-model="count" layout="split" />

    <!-- Stacked layout -->
    <NumberInput v-model="count" layout="stacked" />
</template>

Border Style Variants

Set different border styles via the variant prop for form validation state feedback:

Variant	Description
default	Standard border
error	Error border with danger color focus shadow
success	Success border with success color focus shadow

<template>
    <NumberInput v-model="count" variant="default" />
    <NumberInput v-model="count" variant="error" />
    <NumberInput v-model="count" variant="success" />
</template>

API Reference

NumberInput — Props

Name	Type	Default	Description
layout	"stacked" | "split" | undefined	"split"	Sets how the increment and decrement buttons are arranged around the input.
Details Declared type "stacked" | "split" | undefined Literal values "split" "stacked" Default value details Declaration 'split' Source: packages/ui/src/components/number-input/NumberInput.vue Resolved value "split" Source NumberInput.vue:21 packages/ui/src/components/number-input/NumberInput.vue
variant	"default" | "success" | "error" | undefined	"default"	Sets the default, success, or error border state.
Details Declared type "default" | "success" | "error" | undefined Literal values "default" "error" "success" Default value details Declaration 'default' Source: packages/ui/src/components/number-input/NumberInput.vue Resolved value "default" Source NumberInput.vue:22 packages/ui/src/components/number-input/NumberInput.vue
errorMessage	string | undefined	undefined	Error text shown and associated with the input in the error variant.
Details Declared type string | undefined Default value details Declaration undefined Source: packages/ui/src/components/number-input/NumberInput.vue Resolved value undefined Source NumberInput.vue:23 packages/ui/src/components/number-input/NumberInput.vue
placeholder	string | undefined	undefined	Placeholder shown when the input is empty; the current locale text is used when omitted.
Details Declared type string | undefined Default value details Declaration undefined Source: packages/ui/src/components/number-input/NumberInput.vue Resolved value undefined Source NumberInput.vue:24 packages/ui/src/components/number-input/NumberInput.vue
class	string | undefined	undefined	Custom CSS classes added to the number input container.
Details Declared type string | undefined Default value details Declaration undefined Source: packages/ui/src/components/number-input/NumberInput.vue Resolved value undefined Source NumberInput.vue:25 packages/ui/src/components/number-input/NumberInput.vue
iconSize	IconSize | undefined	"md"	Sets the size of the increment and decrement icons.
Details Declared type IconSize | undefined Literal values "2xl" "lg" "md" "sm" "xl" "xs" Referenced types IconSize Type definition — IconSize export type IconSize = NonNullable<VariantProps<typeof iconSizeVariants>['size']> Default value details Declaration 'md' Source: packages/ui/src/components/number-input/NumberInput.vue Resolved value "md" Source NumberInput.vue:26 packages/ui/src/components/number-input/NumberInput.vue
sound	boolean | undefined	false	Enables a Web Audio click sound when a step control is activated.
Details Declared type boolean | undefined Literal values false true Default value details Declaration false Source: packages/ui/src/components/number-input/NumberInput.vue Resolved value false Source NumberInput.vue:28 packages/ui/src/components/number-input/NumberInput.vue
defaultValue	number | undefined	—	The initial numeric value used in uncontrolled mode.
Details Declared type number | undefined Default value details Not declared — Source NumberInput.vue packages/ui/src/components/number-input/NumberInput.vue
modelValue Nullable	number | null | undefined	—	The current controlled number; null represents an empty value and can be bound with v-model.
Details Declared type number | null | undefined Literal values null Default value details Not declared — Source NumberInput.vue packages/ui/src/components/number-input/NumberInput.vue
min	number | undefined	—	The minimum allowed value and lower bound for decrementing.
Details Declared type number | undefined Default value details Not declared — Source NumberInput.vue packages/ui/src/components/number-input/NumberInput.vue
max	number | undefined	—	The maximum allowed value and upper bound for incrementing.
Details Declared type number | undefined Default value details Not declared — Source NumberInput.vue packages/ui/src/components/number-input/NumberInput.vue
step	number | undefined	—	The amount added or subtracted by each step control activation.
Details Declared type number | undefined Default value details Not declared — Source NumberInput.vue packages/ui/src/components/number-input/NumberInput.vue
stepSnapping	boolean | undefined	—	Whether input values are aligned to multiples of step.
Details Declared type boolean | undefined Literal values false true Default value details Not declared — Source NumberInput.vue packages/ui/src/components/number-input/NumberInput.vue
focusOnChange	boolean | undefined	—	Whether to focus the input after its value changes through a step action.
Details Declared type boolean | undefined Literal values false true Default value details Not declared — Source NumberInput.vue packages/ui/src/components/number-input/NumberInput.vue
formatOptions	Intl.NumberFormatOptions | undefined	—	Intl.NumberFormat options used to format the value and interpret locale-specific input.
Details Declared type Intl.NumberFormatOptions | undefined Default value details Not declared — Source NumberInput.vue packages/ui/src/components/number-input/NumberInput.vue
locale	string | undefined	—	The locale used for number formatting and input parsing.
Details Declared type string | undefined Default value details Not declared — Source NumberInput.vue packages/ui/src/components/number-input/NumberInput.vue
disabled	boolean | undefined	—	Disables the input and its increment and decrement controls.
Details Declared type boolean | undefined Literal values false true Default value details Not declared — Source NumberInput.vue packages/ui/src/components/number-input/NumberInput.vue
readonly	boolean | undefined	—	Prevents direct value editing without disabling the component.
Details Declared type boolean | undefined Literal values false true Default value details Not declared — Source NumberInput.vue packages/ui/src/components/number-input/NumberInput.vue
disableWheelChange	boolean | undefined	—	Prevents the mouse wheel from changing the current value.
Details Declared type boolean | undefined Literal values false true Default value details Not declared — Source NumberInput.vue packages/ui/src/components/number-input/NumberInput.vue
invertWheelChange	boolean | undefined	—	Reverses the mapping between wheel direction and value increment or decrement.
Details Declared type boolean | undefined Literal values false true Default value details Not declared — Source NumberInput.vue packages/ui/src/components/number-input/NumberInput.vue
id	string | undefined	—	The DOM id passed to the internal input control.
Details Declared type string | undefined Default value details Not declared — Source NumberInput.vue packages/ui/src/components/number-input/NumberInput.vue
asChild	boolean | undefined	—	Enables composition mode, merging the component props and behavior into its single child.
Details Declared type boolean | undefined Literal values false true Default value details Not declared — Source NumberInput.vue packages/ui/src/components/number-input/NumberInput.vue
as	AsTag | Component | undefined	—	The tag or Vue component used to render the root element.
Details Declared type AsTag | Component | undefined Literal values "a" "button" "div" "form" "h2" "h3" "img" "input" "label" "li" "nav" "ol" "p" "span" "svg" "template" "ul" Default value details Not declared — Source NumberInput.vue packages/ui/src/components/number-input/NumberInput.vue
name	string | undefined	—	The name of the internal form control for form submission.
Details Declared type string | undefined Default value details Not declared — Source NumberInput.vue packages/ui/src/components/number-input/NumberInput.vue
required	boolean | undefined	—	Marks the internal input control as required.
Details Declared type boolean | undefined Literal values false true Default value details Not declared — Source NumberInput.vue packages/ui/src/components/number-input/NumberInput.vue

NumberInput — Events

Name	Signature or type	Description
@update:modelValue	[val: number]	Emits the new numeric value after typing or stepping so v-model can be updated.
Details Declared type [val: number] Source NumberInput.vue packages/ui/src/components/number-input/NumberInput.vue

Accessibility

• Keyboard: Input supports Tab focus, increment/decrement buttons support Enter/Space trigger, Up/Down arrow keys adjust the value
• ARIA attributes: Increment/decrement buttons automatically set aria-label (e.g. "Increase"/"Decrease"), input sets aria-valuemin, aria-valuemax, aria-valuenow attributes
• Form integration: Supports name, required, disabled, readonly and other native form attributes, compatible with form validation
• Focus management: focusOnChange prop controls whether to auto-focus on value change; all interaction is disabled in disabled state
• Motion & sound degradation: The Drum Ticker micro-animation on value change is disabled automatically under prefers-reduced-motion; the sound effect follows the browser autoplay policy and stays silent before user interaction