Guide / Controls / Inputs

Text box

Type something in

When to use it. A free text entry field. Stores a .string value. Fires action on submit (return key).

Type
textInput
Also titled
Text Input
Default size
1 row × 2 columns
Symbol
character.cursor.ibeam
Docs
Docs complete
Search for it as
  • text field
  • input
  • textbox
  • entry
  • type
  • search box
Text box: Device name field
Rendered by the app

Fields

15 fields you can set on a textInput control. Every control also takes the shared fields (id, position, span, sync, action).

Fields
FieldTypeDefaultWhat it does
placeholderplaceholdertext—

The faint hint inside an empty box

Shows this text in grey inside the field until something is typed.

labellabeltext—

The name shown above the box

Writes this text in the header above the field.

iconicontext—

A small picture at the start of the box

Shows this SF Symbol at the left inside the field.

defaultValuedefaultValuetext—

What is already typed when it first appears

Pre-fills the field with this text when the layout first appears.

stylestylechoiceone of 3default

Which kind of box it is

Switches between a plain field, a search field, or a tall multi-line field.

  • default defaulta plain single-line field with a rounded background
  • searcha field with a magnifying glass and a clear button
  • multilinea tall field that grows for several lines of text
sendButtonsendButtonon / offfalse (off)

A chat-style box with a Send button

On, adds a Send button and makes Return start a new line; off, Return submits.

minLinesminLinesnumber1–20step 11

How tall the box starts

Sets how many text lines tall the composer is when empty, from 1 to 20.

maxLinesmaxLinesnumber1–50step 16

How tall the box can grow

Lets the composer grow up to this many lines (1 to 50) before it scrolls inside.

autocorrectautocorrecton / offfalse (off)

Whether the keyboard fixes your typing

On, the keyboard corrects and capitalizes words; off, it uses a plain ASCII keyboard.

autocorrectToggleautocorrectToggleon / offfalse (off)

A tiny button to switch typing help on the fly

Shows an Aa button that turns autocorrect on or off while the keyboard is open.

keyboardkeyboardchoiceone of 5—

Which keys appear when you tap the box

Chooses the on-screen keyboard layout, such as email or number keys.

  • asciiplain letters and symbols with no suggestions
  • defaultthe standard iPhone keyboard
  • urlkeys for web addresses with a slash and dot
  • emailkeys for email with an at sign
  • numbersa number pad
clearOnSubmitclearOnSubmiton / offfalse (off)

Whether the box empties after sending

Empties the field right after you press return to submit.

tinttintcolor#667eea

The accent color of the box

Colors the cursor, search icon and Send button with this color.

hideBackgroundhideBackgroundon / offfalse (off)

Lets the box sit directly on the page

Removes the frosted card behind the field so it floats on the page.

hideLabelhideLabelon / offfalse (off)

Takes the name off the top

Shows a pill naming the change with an Undo button for 3 seconds after you submit.

Theme fields

Restyle one control by setting these in its theme object; a layout's theme sets them for every control.

Theme fields
FieldTypeDefaultWhat it does
cornerRadiustheme.cornerRadiusnumber0–30 ptstep 112

How big the name above the box is

Sets the header label text size from 8 to 24 points.

Emits and receives

What this control sends when you use it, and what it can show or follow when data arrives.

Emits

Emits
SendsWhenTypeWhat it sends
When you press Return or Sendvaluesubmitstring

the text in the field

With clear on submit the field empties right after sending

Example: Sample A

Receives

Receives
TakesFromTypeWhat it does
valuefollowhub, mqtt, http, store, defaultstring

the text to put in the field

the field shows that text without sending it; your next Return or Send replaces it

Example: Sample A

Sample

The placeholder value the editor shows before real data arrives.

  • Sample A then Sample B

Examples

5 examples, each one a control you can paste into a layout.

Device name field

Shows a pre-filled value (defaultValue), an icon and a placeholder; pressing return broadcasts the typed text through {{value}}.

JSON 10 lines
{
  "type": "textInput",
  "id": "device-name",
  "position": [1, 0],
  "span": [1, 2],
  "placeholder": "Device name",
  "defaultValue": "my-device",
  "icon": "tag",
  "action": { "method": "meshsocket", "mode": "broadcast", "event": "broadcast_request", "payload": { "msg_type": "device_name", "name": "{{value}}" } }
}

Open in CAR-TER

Text box: Device name field
Rendered by the app

Command composer

A growing chat-style box: Send submits, Return adds a newline, and the Aa button flips autocorrect on the live keyboard.

JSON 13 lines
{
  "type": "textInput",
  "id": "pane-input",
  "position": [7, 0],
  "span": [1, 4],
  "placeholder": "type a command…",
  "icon": "chevron.right",
  "sendButton": true,
  "autocorrectToggle": true,
  "autocorrect": false,
  "maxLines": 6,
  "action": { "method": "meshsocket", "mode": "broadcast", "event": "broadcast_request", "payload": { "msg_type": "command", "text": "{{value}}" } }
}

Open in CAR-TER

Text box: Command composer
Rendered by the app

The search look adds a magnifying glass and a clear button, and the field empties itself after each submit (clearOnSubmit).

JSON 11 lines
{
  "type": "textInput",
  "id": "search-box",
  "position": [2, 0],
  "span": [1, 2],
  "label": "Search",
  "placeholder": "Search…",
  "style": "search",
  "clearOnSubmit": true,
  "action": { "method": "meshsocket", "mode": "broadcast", "event": "broadcast_request", "payload": { "msg_type": "search", "q": "{{value}}" } }
}

Open in CAR-TER

Text box: Search box
Rendered by the app

Notes area

The multiline look gives a tall field for several lines of prose, with autocorrect on and the header label hidden.

JSON 11 lines
{
  "type": "textInput",
  "id": "notes",
  "position": [3, 0],
  "span": [2, 2],
  "placeholder": "Jot a note",
  "style": "multiline",
  "autocorrect": true,
  "hideLabel": true,
  "hideBackground": true
}

Open in CAR-TER

Text box: Notes area
Rendered by the app

Email field with confirmation

The email keyboard shows the @ key, and confirm pops an Undo pill for 3 seconds after submit; tint colors the accent.

JSON 12 lines
{
  "type": "textInput",
  "id": "email-entry",
  "position": [4, 0],
  "span": [1, 2],
  "label": "Email",
  "placeholder": "[email protected]",
  "keyboard": "email",
  "tint": "#34c759",
  "confirm": true,
  "action": { "method": "meshsocket", "mode": "broadcast", "event": "broadcast_request", "payload": { "msg_type": "email", "address": "{{value}}" } }
}

Open in CAR-TER

Text box: Email field with confirmation
Rendered by the app

Other keyboards

keyboard can also be url (web address keys) or numbers (number pad); ascii and default pick plain or standard keys. Use the email example above as the pattern and change only keyboard.

Try it on your phone

carterkit serves a small hub on your computer and pushes one example to CAR-TER on your iPhone or iPad. Pair once with the code it prints.

  1. Install the Python kit.

    pip install carterkit
  2. Show “Device name field” on your phone.

    carterkit demo textInput --example 'Device name field'
  3. Swap in any example name from this page, or leave --example off for the first one.

carterkit quickstart · Get CAR-TER

Styles

"default"

Standard single-line text field with rounded background.

Search-style field with magnifying glass icon and clear button.

"multiline"

Expands vertically for multi-line text entry.

Composer & keyboard

Set sendButton: true to turn the field into a growing composer: it grows from minLines up to maxLines then scrolls inside, Return inserts a newline, and a Send button submits. Ideal for chat or command entry.

Keyboard behaviour, tuned for command entry:

  • autocorrect defaults to false — autocorrect/autocapitalization off with an ASCII keyboard, so typed commands aren't "corrected." Set true for prose. keyboard overrides the keyboard type explicitly.
  • autocorrectToggle shows an inline Aa button that flips autocorrect at runtime and reconfigures the live keyboard immediately (no refocus needed). It also appears on the above-keyboard bar.
  • An above-keyboard Hide button lets you dismiss the keyboard to reach the controls/tabs underneath it.

Behavior

  • Default field: the action fires when the user presses return/submit
  • Composer (sendButton: true): Send submits and Return inserts a newline
  • The {{value}} placeholder is replaced with the current text content

Generated from ControlDocs/text-input.md. Something unclear or missing? Tell me.