Number Input
<ahi-number-input> | AhiNumberInput
Number inputs are text fields for entering a formatted numeric value — a plain decimal, a currency amount,
or a value with a unit. The displayed value is formatted (grouping separators, precision, currency/unit
affixes) as the user types, while valueAsNumber and the form-submitted
value remain the raw number.
Number inputs are text fields for entering a formatted numeric value — a plain decimal, a currency amount,
or a value with a unit. The displayed value is formatted (grouping separators, precision, currency/unit
affixes) as the user types, while the form-submitted value and valueAsNumber stay
the raw number.
Use this instead of <ahi-input type="number"> when you need grouping separators,
currency, units, or a fixed number of decimal places. For a simple, unformatted number field,
<ahi-input type="number"> is a lighter choice.
<ahi-number-input label="Quantity" value="12000" help-text="Formatted with grouping separators as you type."></ahi-number-input>
<ahi-number-input> is the input counterpart to
<ahi-format-number>
(which formats a number for display only). The percent style is not currently supported — use
a plain decimal for now.
Examples
Currency
Set type="currency" and a currency code. The symbol, grouping, and decimal
precision follow the locale.
<ahi-number-input type="currency" currency="USD" label="Amount" value="1234.5"></ahi-number-input>
Units
Set type="unit" and a unit (any
ECMAScript sanctioned unit).
<ahi-number-input type="unit" unit="kilogram" label="Weight" value="72"></ahi-number-input>
Precision
Use min-fraction-digits and max-fraction-digits to control the number of decimal
places.
<ahi-number-input label="Rate" min-fraction-digits="2" max-fraction-digits="2" value="3.5"></ahi-number-input>
Min, max, and step
min and max clamp the value on blur and when stepping. The stepper buttons and the
Up/Down arrow keys change the value by step. Set step="0" to hide the steppers.
<ahi-number-input label="Servings" value="1" min="1" max="12" step="1"></ahi-number-input>
Automatic decimal digits
With auto-decimal-digits, the decimal separator is inserted automatically and the trailing
digits are treated as the fraction — typing 1234 yields 12.34. Useful for currency
entry from a numeric keypad.
<ahi-number-input type="currency" currency="USD" auto-decimal-digits label="Amount" value="12.34"></ahi-number-input>
Disabling grouping
Add no-grouping to remove the thousands separators.
<ahi-number-input label="Account number" no-grouping value="12000"></ahi-number-input>
Reading the value
The form-submitted value is the raw number as a string (e.g. "1234.5"). Use the
valueAsNumber property to read or set it as a number.
<ahi-number-input label="Amount" id="ni-read" type="currency" currency="USD" value="1234.5"></ahi-number-input>
<br />
<ahi-button size="small" onclick="alert(document.getElementById('ni-read').valueAsNumber)">Show valueAsNumber</ahi-button>
Importing
To import this component using a script tag:
<script type="module" src="/path/to/azalea-kit-ui/dist/components/number-input/number-input.js"></script>To import this component using a bundler:
import '@azaleahealth/azalea-kit-ui/dist/components/number-input/number-input.js';Slots
| Name | Description |
|---|---|
label
|
The number input’s label. Alternatively, you can use the label attribute. |
help-text
|
Text that describes how to use the number input. Alternatively, use the
help-text attribute.
|
Learn more about using slots.
Properties
| Name | Description | Type | Default | |
|---|---|---|---|---|
value
|
The current value as a raw numeric string (e.g. "1234.5"), submitted as a name/value
pair with form data.
|
string
|
''
|
|
defaultValue
|
The default value of the form control. Primarily used for resetting the form control. |
string
|
''
|
|
label
|
The number input’s label. If you need to display HTML, use the label slot instead.
|
string
|
''
|
|
helpText
help-text
|
The number input’s help text. If you need to display HTML, use the help-text slot
instead.
|
string
|
''
|
|
name
|
The name of the form control, submitted as a name/value pair with form data. |
string
|
''
|
|
disabled
|
Disables the number input. |
boolean
|
false
|
|
readonly
|
Makes the number input read only. |
boolean
|
false
|
|
required
|
Makes the number input a required field. |
boolean
|
false
|
|
clearable
|
Adds a clear button when the input is not empty. |
boolean
|
false
|
|
filled
|
Draws a filled input. |
boolean
|
false
|
|
placeholder
|
Placeholder text to show as a hint when the input is empty. |
string
|
''
|
|
type
|
The formatting style. |
NumberStyle
|
'decimal'
|
|
currency
|
The
ISO 4217
currency code to use when type is currency.
|
string
|
'USD'
|
|
currencyDisplay
currency-display
|
How to display the currency when type is currency. |
'symbol' | 'narrowSymbol' | 'code' | 'name' | 'hidden'
|
'symbol'
|
|
unit
|
The
ECMAScript sanctioned unit
to use when type is unit.
|
string
|
''
|
|
unitDisplay
unit-display
|
How to display the unit when type is unit. |
'long' | 'short' | 'narrow'
|
'short'
|
|
locale
|
The BCP 47 locale to format with. Defaults to the browser’s locale. |
string
|
''
|
|
noGrouping
no-grouping
|
Turns off grouping separators (thousands, lakh, crore, …). |
boolean
|
false
|
|
minFractionDigits
min-fraction-digits
|
The minimum number of fraction digits to display. |
number | undefined
|
- | |
maxFractionDigits
max-fraction-digits
|
The maximum number of fraction digits to display. |
number | undefined
|
- | |
accountingSign
accounting-sign
|
Wrap negative values in parentheses instead of prefixing a minus sign (currency only). |
boolean
|
false
|
|
autoDecimalDigits
auto-decimal-digits
|
Insert the decimal separator automatically, treating the trailing digits as the fraction. |
boolean
|
false
|
|
min
|
The minimum accepted value. The value is clamped to this on blur and when stepping. |
number | undefined
|
- | |
max
|
The maximum accepted value. The value is clamped to this on blur and when stepping. |
number | undefined
|
- | |
step
|
The amount added or subtracted by the stepper buttons and the Up/Down arrow keys. Set to
0 to hide the steppers.
|
number
|
1
|
|
validity
|
Gets the validity state object. | - | - | |
validationMessage
|
Gets the validation message. | - | - | |
valueAsNumber
|
Gets or sets the current value as a number. Returns NaN when the field is empty or
invalid.
|
number
|
- | |
formId
form
|
By default, form controls are associated with the nearest containing
<form> element. This attribute allows you to place the form control outside of a
form and associate it with the form that has this id. The form must be in the same
document or shadow root for this to work.
|
string
|
''
|
|
form
|
The form the control is associated with, following the native form-control contract: reading returns
the associated <form> element (or null if there is none), assigning
takes a form id — assign an empty string to restore association with the nearest containing form.
|
HTMLFormElement | null
|
- | |
updateComplete |
A read-only promise that resolves when the component has finished updating. |
Learn more about properties and attributes.
Events
| Name | Description | Event Detail |
|---|---|---|
ahi-input |
Emitted when the value changes as the user types. | - |
ahi-change |
Emitted when the value is committed (on blur or when stepping). | - |
ahi-focus |
Emitted when the control gains focus. | - |
ahi-blur |
Emitted when the control loses focus. | - |
ahi-clear |
Emitted when the clear button is activated. | - |
ahi-invalid |
Emitted when the form control has been checked for validity and its constraints aren’t satisfied. | - |
Learn more about events.
Methods
| Name | Description | Arguments |
|---|---|---|
stepUp() |
Increments the value by step, clamped to min/max. |
- |
stepDown() |
Decrements the value by step, clamped to min/max. |
- |
focus() |
Sets focus on the number input. |
options: FocusOptions
|
blur() |
Removes focus from the number input. | - |
select() |
Selects all the text in the number input. | - |
checkValidity() |
Checks for validity but does not show a validation message. Returns true when valid and
false when invalid.
|
- |
reportValidity() |
Checks for validity and shows the browser’s validation message if the control is invalid. | - |
setCustomValidity() |
Sets a custom validation message. Pass an empty string to restore validity. |
message: string
|
resetValidity() |
Hides validity again, returning the control to its pristine state: it stops matching
:user-invalid and drops its error styling until the user next interacts with it. The
value and the validity are both untouched — an empty required control is still invalid and still
blocks submission. This only changes whether that invalidity is shown. Interaction state
otherwise has exactly one automatic exit, form.reset(). Call this when the application
replaces a value itself and the old error no longer describes anything the user did: loading a
draft, switching which record is being edited, or clearing a filter row.
|
- |
Learn more about methods.
CSS Parts
| Name | Description |
|---|---|
base |
Deprecated. Use the number-input part instead. |
number-input |
The component’s outer wrapper, an <ahi-input> element. |
spinner |
The container that wraps the increment/decrement buttons. |
increment-button |
The increment (step up) button. |
decrement-button |
The decrement (step down) button. |
Learn more about customizing CSS parts.
Dependencies
This component automatically imports the following dependencies.
<ahi-icon><ahi-input>