Aqua Basis

The AqNumberField component provides an input for numeric values with optional formatting, helper texts, tooltips, and increment/decrement controls. It supports multiple sizes, validation states, and formatting options powered by numbro.js.

<aq-number-field id=aq-number-field-xyhkmd
  format='{"mantissa": 2}'
  label="Example number"
  size="large"
  helper-text="Enter a valid number"
  placeholder="0"
  icon="aq-icon-line-spacing"
  step="1"
  min-value="-50000"
  max-value="50000"
  info="This is a tooltip"
></aq-number-field>

Props and Attributes

Prop / Attr	Type	Default	Description
`format`	`string	object`	`{"mantissa": 0}`
`size`	`'small'	'large'`	`'large'`
`placeholder`	`string`	`'0'`	Placeholder text in the field.
`helperText`	`string`	`''`	Helper text below the field.
`idNumberField`	`string`	`''`	HTML id applied directly to the internal input element.
`name`	`string`	`''`	Name attribute of the input element.
`isError`	`boolean`	`false`	Applies error styling to the input field by setting the outline to the danger primary color while allowing normal interaction.
`isDisabled`	`boolean`	`false`	Disables all user interaction with the component while keeping the placeholder or input visible. Applies less opacity to the elements’ visual style to indicate the disabled state.
`isReadonly`	`boolean`	`false`	Enables readonly mode, allowing the user to see the selected value or placeholder without being able to modify it. Removes the field’s outline and left padding for a cleaner readonly display.
`isPlain`	`boolean`	`false`	Removes the outline from the field in its normal state for a cleaner look. The outline remains visible on hover, when in error state, or when disabled.
`label`	`string`	`''`	Visible label text displayed above the input field.
`info`	`string`	`''`	Text for the tooltip shown when hovering the info icon next to the label.
`tooltipWidth`	`string`	`''`	Maximum width of the info tooltip (e.g., `"200px"`). Leave empty for automatic sizing.
`isRequired`	`boolean`	`false`	Displays a red asterisk next to the label to indicate that the field is required. This is visual only and does not enforce validation.
`step`	`number`	`1`	Amount by which the value increases or decreases when using the arrow keys.
`minValue`	`number`	`-50000`	Minimum allowed value when using step controls. Does not prevent the user from typing a smaller value manually.
`maxValue`	`number`	`50000`	Maximum allowed value when using step controls. Does not prevent the user from typing a larger value manually.
`strictLimitValue`	`boolean`	`false`	Forces the input value to stay within the min and max range. If the user types a value outside the range, it is automatically adjusted to the closest limit.
`isManualInputAllowed`	`boolean`	`true`	Allows or prevents manual typing in the input field. When disabled, the value can only be changed using the increment/decrement buttons.

Props when `size="small"`

Prop / Attr	Type	Default	Description
`icon`	`string`	`'aq-icon-line-spacing'`	Icon name shown to the left of the input when size is `small`.
`leftButtonTooltip`	`string`	`''`	Tooltip text for the left-side icon in `small` size mode. Shown on hover.
`leftButtonTooltipWidth`	`string`	`''`	Maximum width of the tooltip shown on the left-side icon in `small` size mode (e.g., `"200px"`).

PlayGround

You can interact with the component and experiment with its attributes and properties directly in this playground.

In the Code tab, the generated code snippet is available.

In addition to the interactive examples in this documentation, you can explore the full playground with all supported options and advanced configurations at the following link:

👉 Open full playground

https://aqua-ds-playground.masivianlabs.com/doc-storybook/index.html?path=/story/components-forms-aqnumberfield--default&nav=0

<aside> ⚠️

Important: The code shown is in Web Component format. If you are using a specific framework (Vue, React, Angular), you must adapt it to the framework’s conventions before using it.

</aside>

Events

Event	Description	React	Angular	Vue	Vanilla JS
`input`	Triggered each time the field input updates.	`onInput={handleInput}`	`(input)="handleInput($event)"`	`@input="handleInput"`	`addEventListener('input', handler)`
`change`	Triggered when the field content has changed.	`onChange={handleChange}`	`(change)="handleChange($event)"`	`@change="handleChange"`	`addEventListener('change', handler)`

Event Types

Event	React	Angular	Vue
`input`	`(e: React.ChangeEvent<HTMLAqNumberFieldElement> & { nativeEvent: CustomEvent<{ value: string, formattedValue: string, rawValue: string, valueAsNumber: number }> })`	`(e:Event)`	`(e:CustomEvent)`
`change`	`(e: React.ChangeEvent<HTMLAqNumberFieldElement> & { nativeEvent: CustomEvent<{ value: string, formattedValue: string, rawValue: string, valueAsNumber: number }> })`	`(e:Event)`	`(e:CustomEvent)`

Methods

| --- | --- |

Binding Support by Framework

| --- | --- | --- | --- |

Number Formatting with Numbro.js

Some Aqua components that handle numeric values (such as AqNumberField) rely on numbro.js to provide advanced formatting options.

Using numbro, you can define how numbers are displayed, including:

Thousands separators
Decimal precision