Skip to content
Kimenpre-v1documentation home
Color scheme

ki-number-input

Use NumberInput when a person can type an exact quantity, limit, or price. Supply a visible label. Add steppers when incrementing or decrementing the value is common. Use unit for a separate suffix such as seconds.

Theme for this example
Color scheme for this example
<ki-number-input label="Seats" value="3" min="1" max="50" steppers></ki-number-input>
Theme for this example
Color scheme for this example
<ki-number-input label="Timeout" value="30" min="0" unit="seconds"></ki-number-input>

Localized display and form values

Set format to Intl.NumberFormatOptions in JavaScript or to a JSON object in HTML. The nearest lang supplies the locale. The editor shows an ungrouped, full-precision number while focused, then reapplies the display format on blur. A percentage uses percentage points in the editor and a ratio in value and FormData. For example, entering 12,5 in German submits 0.125.

Theme for this example
Color scheme for this example
<ki-number-input lang="de-DE" label="Discount" name="discount" value="0.125" min="0" max="1" step="0.005" format='{"style":"percent","maximumFractionDigits":1}'></ki-number-input>

Set name to include the field in the form and required when it must have a number. Set help-text for instructions and error-text for a validation message. A form reset restores the value attribute. Listen for input for live edits and change for a commit, then read the host’s numeric value.

Keyboard and assistive technology

Tab focuses the spinbutton. Arrow Up and Arrow Down adjust by step, which is 1 by default. Shift with either arrow or Page Up and Page Down adjust by ten steps. Home and End go to the minimum or maximum when supplied. The unit is part of the accessible description, and the optional stepper buttons have their own names and are disabled at the bounds. On blur, an out-of-range number moves to the nearest bound and a polite status explains the adjustment. Localize the buttons and messages through the label and message props.

API reference

When to use: Collect a number like a quantity, amount, or limit. Provide a visible label and choose bounds and an increment when they have meaning.

When not to use: Use ki-input for identifiers, codes, or other text that only looks numeric. Use a range control when relative position is the main cue.

Properties & attributes

AttributePropertyTypeDefaultDescription
decrease-labeldecreaseLabelstring'Decrease {label}'Stepper's accessible name. The field label replaces {label}.
disableddisabledbooleanfalsePrevents editing and excludes the control from form submission.
error-texterrorTextstring | undefined–Validation hint to show when the entry fails a constraint.
formatformatstring–Intl.NumberFormat options for display. In HTML or a catalog spec, supply these options as JSON text. The form value retains its original precision.
help-texthelpTextstring | undefined–Context or instructions displayed beneath the field when it has no visible error.
increase-labelincreaseLabelstring'Increase {label}'Stepper's accessible name. The field label replaces {label}.
invalid-number-messageinvalidNumberMessagestring'Enter a number.'Default validation message for text that cannot be read as a number.
labellabelstring–Visible accessible name. Supply a meaningful label in the page language.
maxmaxnumber | undefined–Maximum permitted numeric value. Omit for an unbounded maximum.
maximum-messagemaximumMessagestring'Value adjusted to the maximum of {value}.'Polite adjustment message after exceeding the maximum. The formatted bound replaces {value}.
minminnumber | undefined–Minimum permitted numeric value. Omit for an unbounded minimum.
minimum-messageminimumMessagestring'Value adjusted to the minimum of {value}.'Polite adjustment message after falling below the minimum. The formatted bound replaces {value}.
namenamestring | undefined–Form-data key for the plain numeric value.
requiredrequiredbooleanfalseWhether the user must enter a number before submitting the form.
stepstepnumber1Positive increment for arrows and buttons. Page keys and Shift+arrows move ten increments.
stepperssteppersbooleanfalseShows named decrease and increase buttons inside the field.
unitunitstring | undefined–Visible suffix such as seconds or seats, included in the accessible description.
valuevaluenumber | undefined–Current numeric value, or undefined when empty or unparseable. Use the attribute for the form reset value. Property assignments are silent.

Events

EventDetail typeDescription
changeEventComposed event fired when the person commits an edited or stepped value. Read the host's numeric value. Listen to native input for live edits.

CSS parts

PartDescription
decreaseButton that subtracts one step.
errorPolite validation feedback associated with the spinbutton.
fieldEnclosure around the editor, unit and stepper buttons.
helpHelp message associated with the spinbutton.
increaseButton that adds one step.
inputNative text editor carrying the spinbutton role.
labelVisible name of the spinbutton.
statusPolite feedback explaining a value adjustment.
unitVisible unit referenced by the spinbutton's description.

CSS custom properties

The public styling contract of ki-number-input: reassign these tokens at :root or on a subtree — never override internals.

TokenDescription
--ki-density-control-offsetAdded to the block size of every scaled control and row (button, icon button, field, select, textarea, option, list item, tab). Components floor the result at ki.size.target-min.
--ki-density-target-minThe smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1).
--ki-focus-ring-colorColour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme.
--ki-focus-ring-offsetGap between a focusable component and its keyboard focus ring.
--ki-focus-ring-widthThickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once.
--ki-number-input-border-block-end-widthField border width at block end.
--ki-number-input-border-block-start-widthField border width at block start.
--ki-number-input-border-inline-widthField border width at either inline edge.
--ki-number-input-field-backdrop-filterComplete backdrop filter behind the field.
--ki-number-input-field-bgResting NumberInput field fill.
--ki-number-input-field-bg-imageOptional theme image layered over the field fill.
--ki-number-input-field-borderResting NumberInput field boundary.
--ki-number-input-field-disabled-bgField fill when disabled.
--ki-number-input-field-disabled-borderBoundary when the entire field is disabled.
--ki-number-input-field-disabled-fgNumeric entry ink when disabled.
--ki-number-input-field-fgForeground of the numeric entry.
--ki-number-input-field-focus-bgField fill while focused.
--ki-number-input-field-focus-fgNumeric entry ink while focused.
--ki-number-input-field-invalid-borderField boundary when a validation message is visible.
--ki-number-input-font-sizeFont size of the numeric entry and its suffix.
--ki-number-input-font-size-touchMinimum input font size under a coarse pointer.
--ki-number-input-heightMedium field height before applying regional density.
--ki-number-input-label-font-sizeField label font size.
--ki-number-input-label-font-weightField label font weight.
--ki-number-input-label-gapGap between the label, field and supporting messages.
--ki-number-input-label-line-heightLine height of the field label.
--ki-number-input-line-heightLine height of the numeric entry and its suffix.
--ki-number-input-padding-inlineInline padding for the plain field and unit suffix.
--ki-number-input-radiusField corners.
--ki-number-input-stepper-bgResting stepper button fill.
--ki-number-input-stepper-disabled-fgStepper icon ink when disabled.
--ki-number-input-stepper-fgResting stepper icon ink.
--ki-number-input-stepper-hover-bgStepper fill when hovered.
--ki-number-input-stepper-hover-fgStepper icon ink when hovered.
--ki-number-input-stepper-padding-inlineEditor inline padding between the steppers.
--ki-number-input-unit-bgBacking of the unit suffix within the field.
--ki-number-input-unit-fgUnit suffix ink. Medium emphasis in the standard contrast setting.
--ki-text-danger-high-emsemantic color for text danger high em.
--ki-text-high-emsemantic color for text high em.
--ki-text-supportingSupporting text of an enabled control: field labels, placeholders, list secondary lines, quiet button labels and unselected tabs. A role, distinct from the med-em emphasis step it resolves to, so a mode can strengthen enabled supporting text without touching the disabled ink that also draws from med-em (directly, or through text.muted).
--ki-typography-family-bodysemantic font family for typography family body.
--ki-typography-line-height-caption-2semantic dimension for typography line height caption 2.
--ki-typography-size-caption-2semantic dimension for typography size caption 2.
--ki-typography-weight-body-normalsemantic font weight for typography weight body normal.

Workshop

Open NumberInput in Storybook