NumberField
Numeric input field with built-in increment/decrement controls, min/max/step clamping, precision formatting, hold-to-repeat, split layout, and full form validation support.
Preview
Rendering the live preview…
defaultRendering the live preview…
splitRendering the live preview…
compactRendering the live preview…
disabledStructure
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<origam-number-field> — 6 parts: root field, input area, control container, increment button, decrement button, and messages/details row.- 1.origam-number-field
- Root OrigamField container. Holds the label, input area, and details zone.
- 2.origam-messages (details slot)
- Details zone below the field — renders hint, error messages, and counter.
- 3.origam-number-field__control
- Wrapper for the stacked or split increment/decrement buttons.
- 4.origam-number-field__compact-input
- Compact-mode inner input shown between the stacked controls.
- 5increment button
- Increment (+) button. aria-label="Increment". Disabled when value >= max.
- 6decrement button
- Decrement (−) button. aria-label="Decrement". Disabled when value <= min.
API
Props
All props accepted by this component, with their type, default value and description.
- autofocusbooleanfalse
- Auto-focuses the input on mount.
- placeholderstring
- Placeholder text shown when the field is empty and not focused.
- persistentPlaceholderbooleanfalse
- Keeps the placeholder visible even when the field is focused.
- rolestring
- modelModifiersstring | boolean
- insetboolean
- hideInputbooleanfalse
- Hides the text input, leaving only the increment/decrement controls visible.
- modelValuenumber | nullnull
- The current numeric value. Use v-model to bind two-way.
- minnumber
- Minimum allowed value. Clamps the model and disables the decrement button when reached.
- maxnumber
- Maximum allowed value. Clamps the model and disables the increment button when reached.
- stepnumber1
- Increment/decrement step size. Also used as the native <input type="number" step> attribute.
- precisionnumber
- Number of decimal places. When set, the displayed value is formatted with toFixed(precision).
- Icon for the increment (+) control button.
- Icon for the decrement (−) control button.
- holdDelaynumber500
- Milliseconds before hold-to-repeat starts when holding a control button.
- holdRepeatnumber100
- Interval in milliseconds between repeated increments/decrements during hold.
- splitbooleanfalse
- Places the decrement button to the left and increment button to the right of the input.
- hideControlsbooleanfalse
- Hides the increment/decrement control buttons entirely.
- compactbooleanfalse
- Compact layout: buttons are stacked vertically to the right of the input.
- decrementAriaLabelstring
- incrementAriaLabelstring
- centerAffixboolean
- dirtyboolean
- disabledbooleanfalse
- Disables the field and all controls.
- errorstring | boolean
- inlineboolean
- labelstring
- Floating label text displayed above / inside the field.
- prefixstring
- suffixstring
- persistentClearboolean
- singleLineboolean
- requiredboolean
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- Shows a loading indicator inside the field.
- colorTColor
- tagstring
- loadingTextstring
- bgColorTColor
- appendInnerAvatarstring
- appendInnerIcon
- Icon displayed inside the field, after the input (overridden by controls when hideControls=false).
- prependInnerAvatarstring
- prependInnerIcon
- Icon displayed inside the field, before the input.
- clearIconTIcon
- clearableboolean
- prependInnerAriaLabelstring
- appendInnerAriaLabelstring
- borderboolean | number | string | TDirectionBoth | Array<TDirectionBoth>
- borderTopboolean | number | string
- borderLeftboolean | number | string
- borderBottomboolean | number | string
- borderRightboolean | number | string
- borderBlockboolean | number | string
- borderInlineboolean | number | string
- borderInlineStartboolean | number | string
- borderInlineEndboolean | number | string
- borderBlockStartboolean | number | string
- borderBlockEndboolean | number | string
- borderColorstring
- borderStylestring
- borderTopColorTColor
- borderRightColorTColor
- borderBottomColorTColor
- borderLeftColorTColor
- borderInlineStartColorTColor
- borderInlineEndColorTColor
- borderBlockStartColorTColor
- borderBlockEndColorTColor
- focusedboolean
- densityTDensity
- textstring
- floatingboolean
- namestring
- marginboolean | number | string
- marginTopboolean | number | string
- marginLeftboolean | number | string
- marginBottomboolean | number | string
- marginRightboolean | number | string
- marginBlockboolean | number | string
- marginInlineboolean | number | string
- marginInlineStartboolean | number | string
- marginInlineEndboolean | number | string
- marginBlockStartboolean | number | string
- marginBlockEndboolean | number | string
- paddingboolean | number | string
- paddingTopboolean | number | string
- paddingLeftboolean | number | string
- paddingBottomboolean | number | string
- paddingRightboolean | number | string
- paddingBlockboolean | number | string
- paddingInlineboolean | number | string
- paddingInlineStartboolean | number | string
- paddingInlineEndboolean | number | string
- paddingBlockStartboolean | number | string
- paddingBlockEndboolean | number | string
- roundedboolean | number | string | TRounded | null | undefined
- roundedTopRightboolean | number | string
- roundedTopLeftboolean | number | string
- roundedBottomLeftboolean | number | string
- roundedBottomRightboolean | number | string
- roundedStartStartboolean | number | string
- roundedStartEndboolean | number | string
- roundedEndStartboolean | number | string
- roundedEndEndboolean | number | string
- fontSizeTFontSize
- fontWeightTFontWeight
- lineHeightTLineHeight
- letterSpacingTLetterSpacing
- activeboolean | IStateEffectConfig
- activeClassstring
- Visual variant: outlined, filled, underlined, solo, plain, ghost.
- elevationTElevation
- sizeTSize | number
- hideDetailsboolean | string
- hideSpinButtonsboolean
- hintstring
- Helper text shown below the field.
- persistentHintbooleanfalse
- Keeps the hint text visible even when the field is not focused.
- messagesArray<string> | string
- heightnumber | string
- maxHeightnumber | string
- maxWidthnumber | string
- minHeightnumber | string
- minWidthnumber | string
- widthnumber | string
- directionTDirection
- errorMessagesArray<string> | string[]
- External error messages injected directly (e.g. from server validation).
- maxErrorsnumber | string
- readonlybooleanfalse
- Makes the field read-only. Controls are hidden in readonly mode.
- rulesArray<any>[]
- Validation rules. Each rule is a function receiving the value and returning true or an error string.
- validateOnTValidateOn
- validationValueany
- appendAvatarstring
- appendIcon
- Icon displayed outside and after the field.
- prependAvatarstring
- prependIcon
- Icon displayed outside and before the field.
- prependAriaLabelstring
- appendAriaLabelstring
API
Slots
Content slots exposed by this component.
- #field
- Replaces the entire field control area.
- #increment
- Custom increment button. Receives handler functions and the canIncrease state.
- #decrement
- Custom decrement button. Receives handler functions and the canDecrease state.
- #default
- Replaces the internal <input> element. Useful for custom input rendering.
- #loader
- Custom loading indicator shown when loading=true.
- #label
- Custom label content replacing the default floating label.
- #floatingLabel
- #prefix
- #suffix
- #prependInner
- Content placed inside the field, before the input.
- #appendInner
- #clear
- #details
- Replaces the entire details area (messages + counter).
- #prepend
- Content placed outside and before the field.
- #append
- Content placed outside and after the field.
- #messages
- Custom message renderer below the field.
- #message
API
Emits
Events emitted by this component.
- @click:controlMouseEvent
- Fired when either the increment or decrement button is clicked.
- @mousedown:controlMouseEvent
- Fired on pointerdown on a control button (used to start hold-to-repeat).
- @click:clearMouseEvent
- Fired when the clear button is clicked (clearable=true).
- @incrementnumber | null
- Fired after each increment step, carrying the new value.
- @decrementnumber | null
- Fired after each decrement step, carrying the new value.
- @update:focusedany
- @click:appendInnerMouseEvent
- @click:prependInnerMouseEvent
- @update:modelValueany
- Two-way binding for the numeric value. Fired on each change.
- @click:appendMouseEvent
- @click:prependMouseEvent
Customisation
CSS variables
CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.
- Field background color.
- Field text color.
- Default border color. Overridden to focus / error variants on interaction.
- Border-radius of the field container.
- Opacity applied when disabled=true.
- Background of the increment button on hover.
- Background of the decrement button on hover.
Inclusion
Accessibility
ARIA roles, keyboard navigation and focus management. Sourced from the real component template.
ARIA roles
Keyboard interactions
| Key | Action |
|---|---|
| ArrowUp | Increments the value by step. |
| ArrowDown | Decrements the value by step. |
| Tab | Moves focus to the next interactive element (input → increment → decrement). |
Notes
- The control container has role="group" and aria-label matching the field label, grouping the input + buttons semantically.
- Increment and decrement buttons have aria-label="Increment" and aria-label="Decrement" respectively. They also have aria-hidden="true" on their icon children.
- When value reaches min or max, the corresponding button is disabled (pointer-events: none, aria-disabled="true").
Interactive
Playground
Edit props live and see the component update in real time. The generated code snippet updates as you change values.
Rendering the live preview…
Usage
Examples
Ready-to-paste code snippets for your templates.
Basic
Split layout
Compact stacked controls