> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperwisor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Text Input

> Capture text (and more) from the user — input types, validation, and how to use the value.

<Info>
  **Category:** Controls · **Sends commands:** via triggers/scripts · **Emits a value:** yes (to scripts)
</Info>

## Mental model

A **Text Input is a form field.** It captures what the user types (or picks, or
scans) and hands that value to your logic. Think of it as the *entry point* for
user-supplied data on a dashboard.

## When to use it

* Let a user enter a name, note, setpoint, or code
* Offer a dropdown / checklist choice
* Scan a QR value into a field

## Settings

### General

* **Widget Title / ID**
* **Input type** — text, select, checklist, etc.
* **Placeholder** · **default value**
* **Max length** · **Pattern (regex)** — validation
* **Select / Checklist options** — one per line, for choice inputs
* **Enable QR scan** — scan a code into the field
* **Show submit / clear button** · **submit label**

### Style

Background, border (color / width / radius), text color, font size, input height,
padding.

### Triggers

| Event                            | Fires when                                                |
| -------------------------------- | --------------------------------------------------------- |
| `input`                          | Each keystroke                                            |
| `change`                         | Value changed (on blur / commit)                          |
| `submit`                         | The submit button is pressed                              |
| `clear`                          | Cleared                                                   |
| `focus` / `blur`                 | Field focus changes                                       |
| `keydown` / `keyup` / `keypress` | Key events                                                |
| *(common)*                       | `load`, `ready`, `destroy`, `update`, `visible`, `hidden` |

## Using the entered value

<Note>
  A Text Input does **not** auto-inject its value into a trigger's command params
  (only [Slider, Color Picker, and Form](/dashboard/triggers#widgets-that-emit-a-value-auto-injected-params)
  do). To act on the typed value, use the **[Script API](/script/overview)** — the
  event carries the value.
</Note>

```js theme={null}
// change fires with the raw value; submit fires with { value }
widget.on('nameInput', 'change', (value) => {
  widget.setText('preview', 'Entered: ' + value);
});

widget.on('nameInput', 'submit', (data) => {
  ws.send(context.deviceId, { command: 'setName', name: data.value });
});
```

Or drop the input inside a [Form](/dashboard/widgets/form) — a Form *does*
auto-inject its fields on submit, so you get the values in the command params for
free.

<CardGroup cols={2}>
  <Card title="Form" icon="table-list" href="/dashboard/widgets/form">
    Multiple fields that auto-inject on submit.
  </Card>

  <Card title="Script API" icon="code" href="/script/overview">
    React to the entered value.
  </Card>
</CardGroup>