ki-number-input
@kimen/elements/ki-number-input- Source
- Agent reference
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.
<ki-number-input label="Seats" value="3" min="1" max="50" steppers></ki-number-input><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.
<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
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
decrease-label | decreaseLabel | string | 'Decrease {label}' | Stepper's accessible name. The field label replaces {label}. |
disabled | disabled | boolean | false | Prevents editing and excludes the control from form submission. |
error-text | errorText | string | undefined | – | Validation hint to show when the entry fails a constraint. |
format | format | string | – | 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-text | helpText | string | undefined | – | Context or instructions displayed beneath the field when it has no visible error. |
increase-label | increaseLabel | string | 'Increase {label}' | Stepper's accessible name. The field label replaces {label}. |
invalid-number-message | invalidNumberMessage | string | 'Enter a number.' | Default validation message for text that cannot be read as a number. |
label | label | string | – | Visible accessible name. Supply a meaningful label in the page language. |
max | max | number | undefined | – | Maximum permitted numeric value. Omit for an unbounded maximum. |
maximum-message | maximumMessage | string | 'Value adjusted to the maximum of {value}.' | Polite adjustment message after exceeding the maximum. The formatted bound replaces {value}. |
min | min | number | undefined | – | Minimum permitted numeric value. Omit for an unbounded minimum. |
minimum-message | minimumMessage | string | 'Value adjusted to the minimum of {value}.' | Polite adjustment message after falling below the minimum. The formatted bound replaces {value}. |
name | name | string | undefined | – | Form-data key for the plain numeric value. |
required | required | boolean | false | Whether the user must enter a number before submitting the form. |
step | step | number | 1 | Positive increment for arrows and buttons. Page keys and Shift+arrows move ten increments. |
steppers | steppers | boolean | false | Shows named decrease and increase buttons inside the field. |
unit | unit | string | undefined | – | Visible suffix such as seconds or seats, included in the accessible description. |
value | value | number | undefined | – | Current numeric value, or undefined when empty or unparseable. Use the attribute for the form reset value. Property assignments are silent. |
Events
| Event | Detail type | Description |
|---|---|---|
change | Event | Composed 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
| Part | Description |
|---|---|
decrease | Button that subtracts one step. |
error | Polite validation feedback associated with the spinbutton. |
field | Enclosure around the editor, unit and stepper buttons. |
help | Help message associated with the spinbutton. |
increase | Button that adds one step. |
input | Native text editor carrying the spinbutton role. |
label | Visible name of the spinbutton. |
status | Polite feedback explaining a value adjustment. |
unit | Visible 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.
| Token | Description |
|---|---|
--ki-density-control-offset | Added 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-min | The 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-color | Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. |
--ki-focus-ring-offset | Gap between a focusable component and its keyboard focus ring. |
--ki-focus-ring-width | Thickness 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-width | Field border width at block end. |
--ki-number-input-border-block-start-width | Field border width at block start. |
--ki-number-input-border-inline-width | Field border width at either inline edge. |
--ki-number-input-field-backdrop-filter | Complete backdrop filter behind the field. |
--ki-number-input-field-bg | Resting NumberInput field fill. |
--ki-number-input-field-bg-image | Optional theme image layered over the field fill. |
--ki-number-input-field-border | Resting NumberInput field boundary. |
--ki-number-input-field-disabled-bg | Field fill when disabled. |
--ki-number-input-field-disabled-border | Boundary when the entire field is disabled. |
--ki-number-input-field-disabled-fg | Numeric entry ink when disabled. |
--ki-number-input-field-fg | Foreground of the numeric entry. |
--ki-number-input-field-focus-bg | Field fill while focused. |
--ki-number-input-field-focus-fg | Numeric entry ink while focused. |
--ki-number-input-field-invalid-border | Field boundary when a validation message is visible. |
--ki-number-input-font-size | Font size of the numeric entry and its suffix. |
--ki-number-input-font-size-touch | Minimum input font size under a coarse pointer. |
--ki-number-input-height | Medium field height before applying regional density. |
--ki-number-input-label-font-size | Field label font size. |
--ki-number-input-label-font-weight | Field label font weight. |
--ki-number-input-label-gap | Gap between the label, field and supporting messages. |
--ki-number-input-label-line-height | Line height of the field label. |
--ki-number-input-line-height | Line height of the numeric entry and its suffix. |
--ki-number-input-padding-inline | Inline padding for the plain field and unit suffix. |
--ki-number-input-radius | Field corners. |
--ki-number-input-stepper-bg | Resting stepper button fill. |
--ki-number-input-stepper-disabled-fg | Stepper icon ink when disabled. |
--ki-number-input-stepper-fg | Resting stepper icon ink. |
--ki-number-input-stepper-hover-bg | Stepper fill when hovered. |
--ki-number-input-stepper-hover-fg | Stepper icon ink when hovered. |
--ki-number-input-stepper-padding-inline | Editor inline padding between the steppers. |
--ki-number-input-unit-bg | Backing of the unit suffix within the field. |
--ki-number-input-unit-fg | Unit suffix ink. Medium emphasis in the standard contrast setting. |
--ki-text-danger-high-em | semantic color for text danger high em. |
--ki-text-high-em | semantic color for text high em. |
--ki-text-supporting | Supporting 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-body | semantic font family for typography family body. |
--ki-typography-line-height-caption-2 | semantic dimension for typography line height caption 2. |
--ki-typography-size-caption-2 | semantic dimension for typography size caption 2. |
--ki-typography-weight-body-normal | semantic font weight for typography weight body normal. |