NumberBox

A NumberBox component allows users to input numeric values: either integer or floating point numbers. It also accepts empty values, where the stored value will be of type null.

The NumberBox is an input control component and is often used in forms. See the Using Forms 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>

endIcon

This property sets an 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>

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>

endText

This property sets a 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>

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>

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>

initialValue

This property sets the component's initial value.

The initial value displayed in the input field.

<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>

label

This property sets the label of the component.

labelBreak (default: false)

This boolean value indicates if the NumberBox labels 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:

labelWidth

This property sets the width of the NumberBox.

maxLength

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

maxValue

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.

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>

minValue

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.

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

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

placeholder

A 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>

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>

required

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

startIcon

This property sets an 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>

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>

startText

This property sets a 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>

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>

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>

validationStatus (default: "none")

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

Available values:

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

<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>

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>

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):

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 method sets the focus on the NumberBox.

setValue

You can use this method to set the component's current value programmatically (true: checked, false: unchecked).

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>

value

You can query the component's value. If no value is set, it will retrieve 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.

Styling

The NumberBox component uses these theme variables to customize its appearance:

• borderRadius-NumberBox
• textColor-NumberBox
• backgroundColor-NumberBox--disabled
• borderWidth-NumberBox
• borderStyle-NumberBox
• borderColor-NumberBox--disabled
• backgroundColor-NumberBox--disabled
• textColor-NumberBox--disabled
• borderColor-NumberBox-default
• borderColor-NumberBox-error
• borderColor-NumberBox-warning
• borderColor-NumberBox-success
• textColor-placeholder-NumberBox

{
  "id": "custom",
  "name": "Custom Theme",
  "themeVars": {
    "borderRadius-NumberBox": "30px",
    "color-adornment-NumberBox": "red",
    "borderWidth-NumberBox": "4px"
  }
}

To style all input controls not just this component, use Input instead of the NumberBox segment:

borderColor-Input: "#0033FF"

Input affects the following controls:

• Checkbox
• RadioGroupOption
• Select
• Switch
• TextArea
• TextBox

See custom themes for styling details.

Theme Variables