---
description: An editable text field for inputting single-line values.
title: Text input fields
image: images/blockly_banner.png
---

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

# Text input fields

A text input field stores a string as its value and a string as its text. Its
value is always a valid string, while its text could be any string entered into
its editor.

#### Text input field

![A block with the label "text input:" and a text input field set to "default
text".](/images/fields/text-input/on_block.png)

#### Text input field with editor open

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

#### Text input field on collapsed block

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

## Creation

<Tabs groupId="group-1">
  <TabItem value="json" label="JSON" default>
  ```js
  {
    "type": "example_textinput",
    "message0": "text input: %1",
    "args0": [
      {
        "type": "field_input",
        "name": "FIELDNAME",
        "text": "default text",
        "spellcheck": false
      }
    ]
  }
  ```
  </TabItem>
  <TabItem value="javascript" label="JavaScript">
  ```js
  Blockly.Blocks['example_textinput'] = {
    init: function() {
      this.appendDummyInput()
          .appendField("text input:")
          .appendField(new Blockly.FieldTextInput('default text'),
              'FIELDNAME');
    }
  };
  ```
  </TabItem>
</Tabs>
The text input constructor takes in an optional value and an optional
[validator](#creating-a-text-input-validator). The value should cast to a
string. If it is `null` or `undefined`, an empty string will be used.

The JSON definition also allows you to set the [spellcheck](#spellcheck) option.

## Serialization and XML

<Tabs groupId="group-2">
  <TabItem value="json" label="JSON" default>
  The JSON for a text input field looks like so:
  
  ```js
  {
    "fields": {
      "FIELDNAME": "text"
    }
  }
  ```
  
  Where `FIELDNAME` is a string referencing a text input 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 text input field looks like so:
  
  ```xml
  <field name="FIELDNAME">text</field>
  ```
  
  Where the field's `name` attribute contains a string referencing a text input
  field, and the 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 text input field's ARIA label is `text: <ARIA value>`. The on-block display
has the ARIA role `button`. Activating the field overlays and focuses an HTML
text input.

## Customization

### Spellcheck

The
`setSpellcheck` function can be used to set whether the field spellchecks its input text or not.

### Text input fields with and without spellcheck

![An animated GIF showing two blocks with text input fields. The first block has
spellcheck on and misspelled words are underlined with a wavy red line. The
second block has spellcheck off and misspelled words are not
underlined.](/images/fields/text-input/spellcheck.gif)

Spellchecking is on by default.

This applies to individual fields. If you want to modify all fields change the
`Blockly.FieldTextInput.prototype.spellcheck_` property.

## Creating a text input validator

:::note
For information on validators in general see [Validators](/guides/create-custom-blocks/fields/validators).
:::

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

Here is an example of a validator that removes all `a` characters from the
string:

```
function(newValue) {
  return newValue.replace(/a/g, '');
}
```

![An animated GIF showing a text input field being validated. When the user
types "bbbaaa" and clicks elsewhere, the field is changed to
"bbb".](/images/fields/text-input/validator.gif)
