Counter

A counter component for numeric input with label, hint, and validation.

vu-counter · @velkin/react/counter

Copy page

Import

React

npm i @velkin/react

import { VuCounter } from "@velkin/react/counter";

Examples

API

Props

Prop	Type	Default	Description
name	`string`	—	Form field name for submit (`name` attr).
defaultvalue	`string`	—	Restored on `<form reset>`; falls back to `defaultnumber` (`defaultvalue` attr).
formid	`string`	—	External `<form>` id (`formid` attr).
disabled	`boolean`	—	Non-interactive; blocks stepping and typing (`disabled` attr).
readonly	`boolean`	—	Focusable but cannot change value (`readonly` attr).
required	`boolean`	—	Blocks valid submit when empty (`required` attr).
requiredmessage	`string`	—	Custom `valueMissing` message (`requiredmessage` attr).
label	`string`	""	Plain-text label; slotted `label` wins when assigned.
hint	`string`	""	Helper text; `hint` slot wins when assigned.
id	`string`	""	Host id forwarded to the internal input.
value	`number`	0	Current value; `NaN` when empty with `allowempty`. Default: `0`.
variant	VuCounterVariant	"default"	Field chrome recipe. Default: `"default"`.
tone	VuCounterTone	"normal"	Neutral surface weight. Default: `"normal"`.
size	VuCounterSize	"md"	Control scale. Default: `"md"`.
radius	VuCounterRadius	"md"	Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `md`.
block	`boolean`	false	Stretches the stepper to the container width. Default: `false`.
compact	`boolean`	false	Tighter label/hint/error spacing. Default: `false`.
min	`number`	0	Minimum allowed value. Default: `0`.
max	`number`	—	Optional maximum allowed value.
step	`number`	1	Increment/decrement step size. Default: `1`.
allowtyping	`boolean`	—	Enables direct typing in the number input. Default: `false`.
allowempty	`boolean`	—	Permits an empty field (`NaN`) until blur when typing. Default: `false`.
wrap	`boolean`	false	At bounds, step wraps to the opposite bound. Default: `false`.
commitonly	`boolean`	—	Typing emits `vu-change` on blur only; buttons emit immediately. Default: `false`.
precision	`number`	0	Decimal places applied on blur and programmatic sets. Default: `0`.
placeholder	`string`	""	Shown when the value is empty (`NaN`).
showerrors	`boolean`	—	Shows validation after activation (`showerrors` attr). Default: `false`.
validationactive	`boolean`	—	Drives invalid styling after activation (`validationactive` attr). Default: `false`.
invalid	`boolean`	false	True when last validation found errors (`invalid` attr). Default: `false`.
icondecrease	`string`	—	Iconify id for the decrease button.
iconincrease	`string`	—	Iconify id for the increase button.
defaultnumber	`number`	—	Baseline for `reset()` when `defaultvalue` is unset. Default: `0`.
decreaselabel	`string`	—	Accessible name for the decrease button.
increaselabel	`string`	—	Accessible name for the increase button.
arialabel	`string`	—	Input name when no visible label is present.
holddelay	`number`	—	ms before press-and-hold repeat starts. Default: `400`.
holdinterval	`number`	—	ms between repeats while held. Default: `80`.
holdaccelerate	`boolean`	—	Halves repeat interval after sustained hold. Default: `true`.
allowTyping	`boolean`	false	Enables direct typing in the number input.
allowEmpty	`boolean`	false	Permits an empty field (`NaN`) until blur when typing.
commitOnly	`boolean`	false	Typing emits `vu-change` on blur only; buttons emit immediately.
showErrors	`boolean`	false	Shows validation after activation.
iconDecrease	`"ion:remove"`	"ion:remove"	Iconify id for the decrease button.
iconIncrease	`"ion:add"`	"ion:add"	Iconify id for the increase button.
defaultNumber	`number`	0	Baseline for `reset()` when `defaultvalue` is unset.
decreaseLabel	`string`	""	Accessible name for the decrease button.
increaseLabel	`string`	""	Accessible name for the increase button.
ariaLabel	`string`	""	Input name when no visible label is present.
holdDelay	`number`	400	ms before press-and-hold repeat starts.
holdInterval	`number`	80	ms between repeats while held.
holdAccelerate	`boolean`	true	Halves repeat interval after sustained hold.
validationActive	`boolean`	false	Drives invalid styling after activation.

Events

Event	Detail	Description
vu-change	VuCounterChangeDetail	Value updates (`detail.previous`, `detail.reason`).
vu-clear	VuCounterClearDetail	After `reset()` syncs the default value.
vu-invalid	VuCounterInvalidDetail	When validation messages are recomputed.

Slots

Slot	Description
label	Rich label markup; takes precedence over string `label` when assigned.
hint	Optional helper copy (HTML); overrides string `hint` when assigned.
error	Replaces default validation message list when assigned.
start	Leading unit or symbol inside the field container.
end	Trailing unit or symbol inside the field container.

CSS parts

Part	Description
field	Column stacking label, control row, hint, and error.
label	Label element wired to the input.
start	Leading affix wrapper.
end	Trailing affix wrapper.
container	Stepper chrome (buttons + input).
button	Shared part on decrease and increase buttons.
button--decrease	Decrease button.
button--increase	Increase button.
icon	Shared part on decrease and increase icons.
icon--decrease	Decrease icon.
icon--increase	Increase icon.
input	Numeric input field.
hint	Helper text region.
error-message	Validation error region.
error-line	One default validation string.

Methods

Method	Description
increment	- Increases value by `step`.
decrement	- Decreases value by `step`.
setValue	- Sets value after clamp/snap and emits `vu-change`.
reset	- Restores baseline value and dispatches `vu-clear`.
validateInput	- Recomputes validation messages and syncs validity.

Types

Name	Definition
VuCounterChangeDetail	`{ value: number; previous: number; reason: VuCounterChangeReason; }`
VuCounterClearDetail	`{ value: number; }`
VuCounterInvalidDetail	`{ errors: string[]; }`
VuCounterRadius	`"sm" \| "md" \| "lg" \| "none" \| "full"`
VuCounterSize	`"sm" \| "md" \| "lg"`
VuCounterTone	`"subtle" \| "normal" \| "strong"`
VuCounterVariant	`"outline" \| "default" \| "underline"`

Import

React

API

Props

Prop	Type	Default	Description
name	`string`	—	Form field name for submit (`name` attr).
defaultvalue	`string`	—	Restored on `<form reset>`; falls back to `defaultnumber` (`defaultvalue` attr).
formid	`string`	—	External `<form>` id (`formid` attr).
disabled	`boolean`	—	Non-interactive; blocks stepping and typing (`disabled` attr).
readonly	`boolean`	—	Focusable but cannot change value (`readonly` attr).
required	`boolean`	—	Blocks valid submit when empty (`required` attr).
requiredmessage	`string`	—	Custom `valueMissing` message (`requiredmessage` attr).
label	`string`	""	Plain-text label; slotted `label` wins when assigned.
hint	`string`	""	Helper text; `hint` slot wins when assigned.
id	`string`	""	Host id forwarded to the internal input.
value	`number`	0	Current value; `NaN` when empty with `allowempty`. Default: `0`.
variant	VuCounterVariant	"default"	Field chrome recipe. Default: `"default"`.
tone	VuCounterTone	"normal"	Neutral surface weight. Default: `"normal"`.
size	VuCounterSize	"md"	Control scale. Default: `"md"`.
radius	VuCounterRadius	"md"	Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `md`.
block	`boolean`	false	Stretches the stepper to the container width. Default: `false`.
compact	`boolean`	false	Tighter label/hint/error spacing. Default: `false`.
min	`number`	0	Minimum allowed value. Default: `0`.
max	`number`	—	Optional maximum allowed value.
step	`number`	1	Increment/decrement step size. Default: `1`.
allowtyping	`boolean`	—	Enables direct typing in the number input. Default: `false`.
allowempty	`boolean`	—	Permits an empty field (`NaN`) until blur when typing. Default: `false`.
wrap	`boolean`	false	At bounds, step wraps to the opposite bound. Default: `false`.
commitonly	`boolean`	—	Typing emits `vu-change` on blur only; buttons emit immediately. Default: `false`.
precision	`number`	0	Decimal places applied on blur and programmatic sets. Default: `0`.
placeholder	`string`	""	Shown when the value is empty (`NaN`).
showerrors	`boolean`	—	Shows validation after activation (`showerrors` attr). Default: `false`.
validationactive	`boolean`	—	Drives invalid styling after activation (`validationactive` attr). Default: `false`.
invalid	`boolean`	false	True when last validation found errors (`invalid` attr). Default: `false`.
icondecrease	`string`	—	Iconify id for the decrease button.
iconincrease	`string`	—	Iconify id for the increase button.
defaultnumber	`number`	—	Baseline for `reset()` when `defaultvalue` is unset. Default: `0`.
decreaselabel	`string`	—	Accessible name for the decrease button.
increaselabel	`string`	—	Accessible name for the increase button.
arialabel	`string`	—	Input name when no visible label is present.
holddelay	`number`	—	ms before press-and-hold repeat starts. Default: `400`.
holdinterval	`number`	—	ms between repeats while held. Default: `80`.
holdaccelerate	`boolean`	—	Halves repeat interval after sustained hold. Default: `true`.
allowTyping	`boolean`	false	Enables direct typing in the number input.
allowEmpty	`boolean`	false	Permits an empty field (`NaN`) until blur when typing.
commitOnly	`boolean`	false	Typing emits `vu-change` on blur only; buttons emit immediately.
showErrors	`boolean`	false	Shows validation after activation.
iconDecrease	`"ion:remove"`	"ion:remove"	Iconify id for the decrease button.
iconIncrease	`"ion:add"`	"ion:add"	Iconify id for the increase button.
defaultNumber	`number`	0	Baseline for `reset()` when `defaultvalue` is unset.
decreaseLabel	`string`	""	Accessible name for the decrease button.
increaseLabel	`string`	""	Accessible name for the increase button.
ariaLabel	`string`	""	Input name when no visible label is present.
holdDelay	`number`	400	ms before press-and-hold repeat starts.
holdInterval	`number`	80	ms between repeats while held.
holdAccelerate	`boolean`	true	Halves repeat interval after sustained hold.
validationActive	`boolean`	false	Drives invalid styling after activation.

Events

Event	Detail	Description
vu-change	VuCounterChangeDetail	Value updates (`detail.previous`, `detail.reason`).
vu-clear	VuCounterClearDetail	After `reset()` syncs the default value.
vu-invalid	VuCounterInvalidDetail	When validation messages are recomputed.

Slots

Slot	Description
label	Rich label markup; takes precedence over string `label` when assigned.
hint	Optional helper copy (HTML); overrides string `hint` when assigned.
error	Replaces default validation message list when assigned.
start	Leading unit or symbol inside the field container.
end	Trailing unit or symbol inside the field container.

CSS parts

Part	Description
field	Column stacking label, control row, hint, and error.
label	Label element wired to the input.
start	Leading affix wrapper.
end	Trailing affix wrapper.
container	Stepper chrome (buttons + input).
button	Shared part on decrease and increase buttons.
button--decrease	Decrease button.
button--increase	Increase button.
icon	Shared part on decrease and increase icons.
icon--decrease	Decrease icon.
icon--increase	Increase icon.
input	Numeric input field.
hint	Helper text region.
error-message	Validation error region.
error-line	One default validation string.

Methods

Method	Description
increment	- Increases value by `step`.
decrement	- Decreases value by `step`.
setValue	- Sets value after clamp/snap and emits `vu-change`.
reset	- Restores baseline value and dispatches `vu-clear`.
validateInput	- Recomputes validation messages and syncs validity.

Types

Name	Definition
VuCounterChangeDetail	`{ value: number; previous: number; reason: VuCounterChangeReason; }`
VuCounterClearDetail	`{ value: number; }`
VuCounterInvalidDetail	`{ errors: string[]; }`
VuCounterRadius	`"sm" \| "md" \| "lg" \| "none" \| "full"`
VuCounterSize	`"sm" \| "md" \| "lg"`
VuCounterTone	`"subtle" \| "normal" \| "strong"`
VuCounterVariant	`"outline" \| "default" \| "underline"`

Import

Examples

API

Props

Events

Slots

CSS parts

Methods

Types

Related

Inputs

Guides

Browse

Import

Examples

API

Props

Events

Slots

CSS parts

Methods

Types

Related

Inputs

Guides

Browse