NumberBox

NumberBox provides a specialized input field for numeric values with built-in validation, spinner buttons, and flexible formatting options. It supports both integer and floating-point numbers, handles empty states as null values, and integrates seamlessly with form validation.

Key features:

Flexible numeric input: Accepts integers, floating-point numbers, or empty values (stored as null)
Input constraints: Configure minimum/maximum values, integer-only mode, and positive-only restrictions
Spinner buttons: Built-in increment/decrement buttons with customizable step values and icons
Visual adornments: Add icons or text to the start and end of the input field
Validation: Built-in validation status indicators and form compatibility
Smart paste handling: Only accepts pasted content that results in valid numeric values

The NumberBox is often used in forms. See the this guide for details.

Properties

`autoFocus` (default: false)

If this property is set to true, the component gets the focus automatically when displayed.

If this boolean prop is set to true, the NumberBox input will be focused when appearing on the UI.

`enabled` (default: true)

This boolean property value indicates whether the component responds to user events (true) or not (false).

Controls whether the input field is enabled (true) or disabled (false).

<App>
  <NumberBox enabled="false" />
</App>

Example: enabled

<App>
  <NumberBox enabled="false" />
</App>

`endIcon`

This property sets an optional icon to appear on the end (right side when the left-to-right direction is set) of the input.

This string prop enables the display of an icon on the right side (left-to-right display) of the input field by providing a valid

icon name

<App>
  <NumberBox endIcon="email" />
</App>

Example: endIcon

<App>
  <NumberBox endIcon="email" />
</App>

It is possible to set the other adornments as well: endText, startIcon and startText.

<App>
  <NumberBox startIcon="hyperlink" startText="www." endIcon="email" endText=".com" />
</App>

Example: all adornments

<App>
  <NumberBox startIcon="hyperlink" startText="www." endIcon="email" endText=".com" />
</App>

`endText`

This property sets an optional text to appear on the end (right side when the left-to-right direction is set) of the input.

This string prop enables the display of a custom string on the right side (left-to-right display) of the input field.

<App>
  <NumberBox endText=".com" />
</App>

Example: endText

<App>
  <NumberBox endText=".com" />
</App>

It is possible to set the other adornments as well: endIcon, startIcon and startText.

<App>
  <NumberBox startIcon="hyperlink" startText="www." endIcon="email" endText=".com" />
</App>

Example: all adornments

<App>
  <NumberBox startIcon="hyperlink" startText="www." endIcon="email" endText=".com" />
</App>

`gap`

This property defines the gap between the adornments and the input area.

`hasSpinBox` (default: true)

This boolean prop shows (true) or hides (false) the spinner buttons for the input field.

<App>
  <NumberBox hasSpinBox="true" initialValue="3" />
  <NumberBox hasSpinBox="false" initialValue="34" />
</App>

Example: hasSpinBox

<App>
  <NumberBox hasSpinBox="true" initialValue="3" />
  <NumberBox hasSpinBox="false" initialValue="34" />
</App>

`initialValue`

This property sets the component's initial value.

The initial value displayed in the input field.

<App>
  <NumberBox initialValue="123" />
</App>

Example: initialValue

<App>
  <NumberBox initialValue="123" />
</App>

`integersOnly` (default: false)

This boolean property signs whether the input field accepts integers only (true) or not (false).

<App>
  <NumberBox integersOnly="true" initialValue="42" />
  <NumberBox integersOnly="false" initialValue="{Math.PI}" />
</App>

Example: integersOnly

<App>
  <NumberBox integersOnly="true" initialValue="42" />
  <NumberBox integersOnly="false" initialValue="{Math.PI}" />
</App>

`label`

This property sets the label of the component. If not set, the component will not display a label.

`labelBreak` (default: true)

This boolean value indicates whether the NumberBox label can be split into multiple lines if it would overflow the available label width.

`labelPosition` (default: "top")

Places the label at the given position of the component.

Available values:

Value	Description
`start`	The left side of the input (left-to-right) or the right side of the input (right-to-left)
`end`	The right side of the input (left-to-right) or the left side of the input (right-to-left)
`top`	The top of the input (default)
`bottom`	The bottom of the input

`labelWidth`

This property sets the width of the NumberBox component's label. If not defined, the label's width will be determined by its content and the available space.

`maxLength`

This property sets the maximum length of the input it accepts.

`maxValue` (default: 999999999999999)

The maximum value the input field allows. Can be a float or an integer if integersOnly is set to false, otherwise it can only be an integer.If not set, no maximum value check is done.

The maximum value the input field allows. Can be a float or an integer if integersOnly is set to false, otherwise it can only be an integer.

Try to enter a bigger value into the input field below than the maximum allowed.

<App>
  <NumberBox maxValue="100" initialValue="99" />
</App>

Example: maxValue

<App>
  <NumberBox maxValue="100" initialValue="99" />
</App>

`minValue` (default: -999999999999999)

The minimum value the input field allows. Can be a float or an integer if integersOnly is set to false, otherwise it can only be an integer.If not set, no minimum value check is done.

Try to enter a bigger value into the input field below than the minimum allowed.

<App>
  <NumberBox minValue="-100" initialValue="-99" />
</App>

Example: minValue

<App>
  <NumberBox minValue="-100" initialValue="-99" />
</App>

`placeholder`

An optional placeholder text that is visible in the input field when its empty.

A placeholder text that is visible in the input field when its empty.

<App>
  <NumberBox placeholder="This is a placeholder" />
</App>

Example: placeholder

<App>
  <NumberBox placeholder="This is a placeholder" />
</App>

`readOnly` (default: false)

Set this property to true to disallow changing the component value.

If true, the component's value cannot be modified with user interactions.

<App>
  <NumberBox initialValue="123" readOnly="true" />
</App>

Example: readOnly

<App>
  <NumberBox initialValue="123" readOnly="true" />
</App>

`required` (default: false)

Set this property to true to indicate it must have a value before submitting the containing form.

`spinnerDownIcon`

Allows setting an alternate icon displayed in the NumberBox spinner for decrementing values. You can change the default icon for all NumberBox instances with the "icon.spinnerDown:NumberBox" declaration in the app configuration file.

`spinnerUpIcon`

Allows setting an alternate icon displayed in the NumberBox spinner for incrementing values. You can change the default icon for all NumberBox instances with the "icon.spinnerUp:NumberBox" declaration in the app configuration file.

`startIcon`

This property sets an optional icon to appear at the start (left side when the left-to-right direction is set) of the input.

This string prop enables the display of an icon on the left side (left-to-right display) of the input field by providing a valid

icon name

<App>
  <NumberBox startIcon="hyperlink" />
</App>

Example: startIcon

<App>
  <NumberBox startIcon="hyperlink" />
</App>

It is possible to set the other adornments as well: endText, startIcon and startText.

<App>
  <NumberBox startIcon="hyperlink" startText="www." endIcon="email" endText=".com" />
</App>

Example: all adornments

<App>
  <NumberBox startIcon="hyperlink" startText="www." endIcon="email" endText=".com" />
</App>

`startText`

This property sets an optional text to appear at the start (left side when the left-to-right direction is set) of the input.

This string prop enables the display of a custom string on the left side (left-to-right display) of the input field.

<App>
  <NumberBox startText="www." />
</App>

Example: startText

<App>
  <NumberBox startText="www." />
</App>

It is possible to set the other adornments as well: endIcon, startIcon and endText.

<App>
  <NumberBox startIcon="hyperlink" startText="www." endIcon="email" endText=".com" />
</App>

Example: all adornments

<App>
  <NumberBox startIcon="hyperlink" startText="www." endIcon="email" endText=".com" />
</App>

`step` (default: 1)

This prop governs how big the step when clicking on the spinner of the field.

The default stepping value is 1.

Note that only integers are allowed to be entered.

<App>
  <NumberBox initialValue="10" step="10" />
</App>

Example: step

<App>
  <NumberBox initialValue="10" step="10" />
</App>

`validationStatus` (default: "none")

This property allows you to set the validation status of the input component.

Available values:

Value	Description
`valid`	Visual indicator for an input that is accepted
`warning`	Visual indicator for an input that produced a warning
`error`	Visual indicator for an input that produced an error

This prop is used to visually indicate status changes reacting to form field validation.

Value	Description
`valid`	Visual indicator for an input that is accepted
`warning`	Visual indicator for an input that produced a warning
`error`	Visual indicator for an input that produced an error

<App>
  <NumberBox />
  <NumberBox validationStatus="valid" />
  <NumberBox validationStatus="warning" />
  <NumberBox validationStatus="error" />
</App>

Example: validationStatus

<App>
  <NumberBox />
  <NumberBox validationStatus="valid" />
  <NumberBox validationStatus="warning" />
  <NumberBox validationStatus="error" />
</App>

`zeroOrPositive` (default: false)

This boolean property determines whether the input value can only be 0 or positive numbers (true) or also negative (false).

This boolean property determines whether the input value can only be 0 or positive numbers (true) or also negative (false). By default, this property is set to false.

<App>
  <NumberBox initialValue="123" zeroOrPositive="true" />
</App>

Example: zeroOrPositive

<App>
  <NumberBox initialValue="123" zeroOrPositive="true" />
</App>

Events

`didChange`

This event is triggered when value of NumberBox has changed.

This event is triggered after the user has changed the field value.

Write in the input field and see how the Text underneath it is updated in parallel.

<App var.field="0">
  <NumberBox initialValue="{field}" onDidChange="(val) => field = val" />
  <Text value="{field}" />
</App>

Example: didChange

<App var.field="0">
  <NumberBox initialValue="{field}" onDidChange="(val) => field = val" />
  <Text value="{field}" />
</App>

`gotFocus`

This event is triggered when the NumberBox has received the focus.

This event is triggered when the NumberBox receives focus. The following sample demonstrates this event.

<App var.focused="{false}">
  <NumberBox
    onGotFocus="focused = true"
    onLostFocus="focused = false" />
  <Text>The NumberBox is {focused ? '' : 'not'} focused</Text>
</App>

Click into the NumberBox (and then click the text below):

<App var.focused="{false}">
  <NumberBox
    onGotFocus="focused = true"
    onLostFocus="focused = false" />
  <Text>The NumberBox is {focused ? '' : 'not'} focused</Text>
</App>

Click into the NumberBox (and then click the text below):

`lostFocus`

This event is triggered when the NumberBox has lost the focus.

This event is triggered when the NumberBox loses focus.

(See the example above)

Exposed Methods

`focus`

This API focuses the input field of the NumberBox. You can use it to programmatically focus the field.

Signature: focus(): void

`setValue`

This API sets the value of the NumberBox. You can use it to programmatically change the value.

Signature: setValue(value: number | undefined): void

You can use this method to set the component's current value programmatically.

<App>
  <NumberBox
    id="numberbox"
    readOnly="true"
  />
  <HStack>
    <Button
      label="Set to 100"
      onClick="numberbox.setValue(100)" />
    <Button
      label="Set to 0"
      onClick="numberbox.setValue(0)" />
  </HStack>
</App>

Example: value and setValue

<App>
  <NumberBox
    id="numberbox"
    readOnly="true"
  />
  <HStack>
    <Button
      label="Set to 100"
      onClick="numberbox.setValue(100)" />
    <Button
      label="Set to 0"
      onClick="numberbox.setValue(0)" />
  </HStack>
</App>

`value`

This API retrieves the current value of the NumberBox. You can use it to get the value programmatically.

Signature: get value(): number | undefined

You can query this read-only API property to get the input component's current value.

See an example in the setValue API method.

Parts

The component has some parts that can be styled through layout properties and theme variables separately:

endAdornment: The adornment displayed at the end of the text box.
input: The text box input area.
label: The label displayed for the text box.
startAdornment: The adornment displayed at the start of the text box.

Styling

Theme Variables

Variable	Default Value (Light)	Default Value (Dark)
backgroundColor-NumberBox--disabled	none	none
backgroundColor-NumberBox-default	none	none
backgroundColor-NumberBox-default--focus	none	none
backgroundColor-NumberBox-default--hover	none	none
backgroundColor-NumberBox-error	none	none
backgroundColor-NumberBox-error--focus	none	none
backgroundColor-NumberBox-error--hover	none	none
backgroundColor-NumberBox-success	none	none
backgroundColor-NumberBox-success--focus	none	none
backgroundColor-NumberBox-success--hover	none	none
backgroundColor-NumberBox-warning	none	none
backgroundColor-NumberBox-warning--focus	none	none
backgroundColor-NumberBox-warning--hover	none	none
borderColor-NumberBox--disabled	none	none
borderColor-NumberBox-default	none	none
borderColor-NumberBox-default--focus	none	none
borderColor-NumberBox-default--hover	none	none
borderColor-NumberBox-error	none	none
borderColor-NumberBox-error--focus	none	none
borderColor-NumberBox-error--hover	none	none
borderColor-NumberBox-success	none	none
borderColor-NumberBox-success--focus	none	none
borderColor-NumberBox-success--hover	none	none
borderColor-NumberBox-warning	none	none
borderColor-NumberBox-warning--focus	none	none
borderColor-NumberBox-warning--hover	none	none
borderRadius-NumberBox-default	none	none
borderRadius-NumberBox-error	none	none
borderRadius-NumberBox-success	none	none
borderRadius-NumberBox-warning	none	none
borderStyle-NumberBox-default	none	none
borderStyle-NumberBox-error	none	none
borderStyle-NumberBox-success	none	none
borderStyle-NumberBox-warning	none	none
borderWidth-NumberBox-default	none	none
borderWidth-NumberBox-error	none	none
borderWidth-NumberBox-success	none	none
borderWidth-NumberBox-warning	none	none
boxShadow-NumberBox-default	none	none
boxShadow-NumberBox-default--focus	none	none
boxShadow-NumberBox-default--hover	none	none
boxShadow-NumberBox-error	none	none
boxShadow-NumberBox-error--focus	none	none
boxShadow-NumberBox-error--hover	none	none
boxShadow-NumberBox-success	none	none
boxShadow-NumberBox-success--focus	none	none
boxShadow-NumberBox-success--hover	none	none
boxShadow-NumberBox-warning	none	none
boxShadow-NumberBox-warning--focus	none	none
boxShadow-NumberBox-warning--hover	none	none
color-adornment-NumberBox-default	none	none
color-adornment-NumberBox-error	none	none
color-adornment-NumberBox-success	none	none
color-adornment-NumberBox-warning	none	none
fontSize-NumberBox-default	none	none
fontSize-NumberBox-error	none	none
fontSize-NumberBox-success	none	none
fontSize-NumberBox-warning	none	none
fontSize-placeholder-NumberBox-default	none	none
fontSize-placeholder-NumberBox-error	none	none
fontSize-placeholder-NumberBox-success	none	none
fontSize-placeholder-NumberBox-warning	none	none
gap-adornment-NumberBox	none	none
outlineColor-NumberBox-default--focus	none	none
outlineColor-NumberBox-error--focus	none	none
outlineColor-NumberBox-success--focus	none	none
outlineColor-NumberBox-warning--focus	none	none
outlineOffset-NumberBox-default--focus	none	none
outlineOffset-NumberBox-error--focus	none	none
outlineOffset-NumberBox-success--focus	none	none
outlineOffset-NumberBox-warning--focus	none	none
outlineStyle-NumberBox-default--focus	none	none
outlineStyle-NumberBox-error--focus	none	none
outlineStyle-NumberBox-success--focus	none	none
outlineStyle-NumberBox-warning--focus	none	none
outlineWidth-NumberBox-default--focus	none	none
outlineWidth-NumberBox-error--focus	none	none
outlineWidth-NumberBox-success--focus	none	none
outlineWidth-NumberBox-warning--focus	none	none
padding-NumberBox	none	none
paddingBottom-NumberBox	none	none
paddingHorizontal-NumberBox	$space-2	$space-2
paddingLeft-NumberBox	none	none
paddingRight-NumberBox	none	none
paddingTop-NumberBox	none	none
paddingVertical-NumberBox	$space-2	$space-2
textColor-NumberBox--disabled	none	none
textColor-NumberBox-default	none	none
textColor-NumberBox-default--focus	none	none
textColor-NumberBox-default--hover	none	none
textColor-NumberBox-error	none	none
textColor-NumberBox-error--focus	none	none
textColor-NumberBox-error--hover	none	none
textColor-NumberBox-success	none	none
textColor-NumberBox-success--focus	none	none
textColor-NumberBox-success--hover	none	none
textColor-NumberBox-warning	none	none
textColor-NumberBox-warning--focus	none	none
textColor-NumberBox-warning--hover	none	none
textColor-placeholder-NumberBox-default	none	none
textColor-placeholder-NumberBox-error	none	none
textColor-placeholder-NumberBox-success	none	none
textColor-placeholder-NumberBox-warning	none	none

NumberBox

Properties

autoFocus (default: false)

enabled (default: true)

endIcon

endText

gap

hasSpinBox (default: true)

initialValue

integersOnly (default: false)

label

labelBreak (default: true)

labelPosition (default: "top")

labelWidth

maxLength

maxValue (default: 999999999999999)

minValue (default: -999999999999999)

placeholder

readOnly (default: false)

required (default: false)

spinnerDownIcon

spinnerUpIcon

startIcon

startText

step (default: 1)

validationStatus (default: "none")

zeroOrPositive (default: false)

Events

didChange

gotFocus

lostFocus

Exposed Methods

focus

setValue

value

Parts

Styling

Theme Variables

`autoFocus` (default: false)

`enabled` (default: true)

`endIcon`

`endText`

`gap`

`hasSpinBox` (default: true)

`initialValue`

`integersOnly` (default: false)

`label`

`labelBreak` (default: true)

`labelPosition` (default: "top")

`labelWidth`

`maxLength`

`maxValue` (default: 999999999999999)

`minValue` (default: -999999999999999)

`placeholder`

`readOnly` (default: false)

`required` (default: false)

`spinnerDownIcon`

`spinnerUpIcon`

`startIcon`

`startText`

`step` (default: 1)

`validationStatus` (default: "none")

`zeroOrPositive` (default: false)

`didChange`

`gotFocus`

`lostFocus`

`focus`

`setValue`

`value`