---
description: A field for selecting numeric values.
title: Number fields
image: images/blockly_banner.png
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Number fields

A number field stores a number as its `value`, and a string as its `text`. Its `value`
is always a valid number as defined by the [constraints](#constraints) given to
the field at creation; its text could be any string entered into its editor.

#### Number field

![A block with the label "number:" and a number field set to
100.](/images/fields/number/on_block.png)

#### Number field with editor open

![The same block with the field being
edited.](/images/fields/number/with_editor.png)

#### Number field on collapsed block

![The same block after being collapsed. It has the label "number: 100" and a
jagged right edge to show it is
collapsed.](/images/fields/number/collapsed.png)

## Creation

<Tabs groupId="group-1">
  <TabItem value="json" label="JSON" default>
  ```js
  {
    "type": "example_number",
    "message0": "number: %1",
    "args0": [
      {
        "type": "field_number",
        "name": "FIELDNAME",
        "value": 100,
        "min": 0,
        "max": 100,
        "precision": 10
      }
    ]
  }
  ```
  </TabItem>
  <TabItem value="javascript" label="JavaScript">
  ```js
  Blockly.Blocks['example_number'] = {
    init: function() {
      this.appendDummyInput()
          .appendField("number:")
          .appendField(new Blockly.FieldNumber(100, 0, 100, 10), 'FIELDNAME');
    }
  };
  ```
  </TabItem>
</Tabs>
The number constructor takes in the following:

- an optional `value`
- an optional [`min`](#minimum-value)
- an optional [`max`](#maximum-value)
- an optional [`precision`](#rounding)
- an optional [`validator`](#creating-a-number-validator)

The `value` should cast to a number. If it does not 0 will be used.

## Serialization

<Tabs groupId="group-2">
  <TabItem value="json" label="JSON" default>
  The JSON for a number field looks like so:
  
  ```js
  {
    "fields": {
      "FIELDNAME": 0
    }
  }
  ```
  
  Where `FIELDNAME` is a string referencing a number field, and
  the value is the value to apply to the field. The value
  follows the same rules as the constructor value.
  </TabItem>
  <TabItem value="xml" label="XML">
  The XML for a number field looks like so:
  
  ```xml
  <field name="FIELDNAME">0</field>
  ```
  
  The `field` node's `name` attribute contains a string referencing a number
  field, and the node's inner `text` is the `value` to apply to the field. The
  inner text value follows the same rules as the constructor value.
  </TabItem>
</Tabs>

## Accessibility

A number field's ARIA label is `number: <ARIA value>`. A number fields's 
on-block display has the ARIA role `button`. Activating the field overlays and
focuses an HTML text input.

:::note
The HTML input type is `text` rather than `number` because the semantics of
an HTML `number` input do not match Blockly's behaviour. Blockly number fields
provide feedback for invalid values and handle the value `Infinity`.
[According to MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/number#accessibility)
“the implicit role for the `<input type="number">` element is `spinbutton`. 
[...] With `<input type="number">`, there is a risk of users accidentally 
incrementing a number when they're trying to do something else. Additionally, 
if users try to enter something that's not a number, there's no explicit 
feedback about what they're doing wrong.”
:::

## Constraints

Constraints can be set in the field definition, or by using the
[setConstraints](/reference/blockly.fieldnumber.setconstraints)
function.

### Minimum value

The `min` value sets the smallest/most-negative value the field is allowed to
contain.

### Maximum value

The `max` value sets the largest/most-positive value the field is allowed to
contain.

### Rounding

The `precision` rounds the value to the nearest multiple of precision. This can be
used to make the field only accept multiples of .01, 10, 42, etc.

## Common constraints

### Positive numbers

To force your field to only accept positive numbers, set the `min` value to 1.

### Integers

To force your field to only accept integers, set the `precision` to 1.

## Creating a number validator

:::note
For information on validators in general see [Validators](../validators).
:::

A number field's value is a number, so any validators must accept a `number` and
return a `number`, `null`, or `undefined`.

Here is an example of a validator that changes the value to be either 0 or 1
depending on if the value was odd or even.

```
function(newValue) {
  return newValue % 2;
}
```

![An animated GIF showing the validator at work. When the user types 10 and
clicks elsewhere, the field is set to 0. When the user types 11 and clicks
elsewhere, the field is set to 1.](/images/fields/number/validator.gif)
