# Text Input

Single-line text field. Publishes its value for other components and workflows to use.

## Add it to an app

1. Open the app builder and find **Text Input** in the component palette.
2. Insert it into the intended region or container.
3. Set its properties in the inspector. Use a literal for a fixed value or a binding for a value supplied by the app.
4. Connect its events where the app should respond to a user gesture.
5. Preview with representative data and save after resolving validation problems.

The type name in the builder’s code view is `text_input`.

## Settings

| Setting | Accepted value | Required | Default | What it controls |
| --- | --- | --- | --- | --- |
| Label (`label`) | string | No | "Label" | Supports expression bindings. Shown above the field; also its accessible name. The listed default is inserted when adding a new component. |
| Placeholder (`placeholder`) | string | No | "" | Supports expression bindings. Hint inside the empty field. The listed default is inserted when adding a new component. |

## Values available to bindings

| Value | Type | Initial value | Meaning |
| --- | --- | --- | --- |
| `value` | string | "" | The current text. |

Refer to these values through `components.<component-id>.<value>` in a binding. Use the identifier assigned to this instance of Text Input, not the component type name.

## Events

- `onChange` — Every keystroke, after `value` is published.

- `onSubmit` — Enter pressed in the field.

Connect only the actions the app needs. An event can fetch results, run an enabled data source, set state, update another component, show a notification, or navigate where supported.

## Keyboard and accessible labels

Accessible label source: `label`, else `placeholder`, else 'Text input'.

- Enter fires onSubmit.

## Example: Labelled field

| Setting | Example value |
| --- | --- |
| `label` | "Page URL" |
| `placeholder` | "https://example.com/status" |

## Example: Search on Enter

| Setting | Example value |
| --- | --- |
| `label` | "Search" |
| `placeholder` | "Type and press Enter" |

When `onSubmit` occurs, the example performs:

- `triggerDataSource` with {"dataSourceId":"search","inputRecords":[{"query":"{{ components.Search.value }}"}],"mode":"run"}

## If it is empty or unavailable

Check the source binding, the selected item, and the app’s access. A hosted document, table, review, or storage component needs the corresponding app capability; an offline preview cannot supply live private data. A source running with no results is different from an invalid binding. Inspect the app’s workflow and data source before changing the presentation.