# TextField

```ts
import { TextField } from 'cx/widgets';
```



The `TextField` widget is used for single-line text inputs. It's one of the most commonly used form controls with support for validation, placeholders, icons, and various input modes.

```tsx
import { createModel } from "cx/data";
import { bind, LabelsTopLayout } from "cx/ui";
import { TextField } from "cx/widgets";

interface Model {
  text: string;
  placeholder: string;
}

const m = createModel<Model>();

export default (
  <LabelsTopLayout columns={2}>
    <TextField label="Standard" value={bind(m.text, "Hello World")} autoFocus />
    <TextField label="Disabled" value={m.text} disabled />
    <TextField label="Read-only" value={m.text} readOnly />
    <TextField label="Placeholder" value={m.placeholder} placeholder="Type something..." />
    <TextField label="Required" value={m.text} required />
    <TextField label="Min/Max Length" value={m.text} minLength={3} maxLength={8} />
  </LabelsTopLayout>
);

```

## Styling

TextField supports icons, clear buttons, and custom styling for the input element.

```tsx
import { createModel } from "cx/data";
import { bind, expr, LabelsTopLayout } from "cx/ui";
import { TextField } from "cx/widgets";
import "../../icons/lucide";

interface Model {
  text: string;
  search: string;
  password: string;
  showPassword: boolean;
}

const m = createModel<Model>();

export default (
  <LabelsTopLayout columns={2}>
    <TextField
      label="With Icon"
      value={m.search}
      icon="search"
      placeholder="Search..."
      showClear
    />
    <TextField
      label="Password Toggle"
      value={bind(m.password, "secret123")}
      inputType={expr(m.showPassword, (show) => (show ? "text" : "password"))}
      icon={{
        name: expr(m.showPassword, (show) => (show ? "eye-off" : "eye")),
        style: "pointer-events: all; cursor: pointer",
        onClick: (e, { store }) => {
          e.stopPropagation();
          store.toggle(m.showPassword);
        },
      }}
    />
    <TextField
      label="Custom Input Style"
      value={bind(m.text, "Styled input")}
      inputStyle={{ border: "2px solid #3b82f6", borderRadius: "8px" }}
    />
    <TextField label="View Mode" value={m.text} viewMode emptyText="N/A" />
  </LabelsTopLayout>
);

```

## See Also

- [Forwarding Keyboard Inputs](/docs/forms/list-forwarding-keyboard-inputs) - Forward keyboard events from TextField to a List

## Configuration

### Core Properties

| Property      | Type      | Default                     | Description                                                                                                 |
| ------------- | --------- | --------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `value`       | `string`  | `null`                      | Text value of the input                                                                                     |
| `placeholder` | `string`  |                             | Hint text displayed when the field is empty                                                                 |
| `disabled`    | `boolean` | `false`                     | Disables the input                                                                                          |
| `enabled`     | `boolean` |                             | Opposite of `disabled`                                                                                      |
| `readOnly`    | `boolean` | `false`                     | Makes the input read-only                                                                                   |
| `required`    | `boolean` | `false`                     | Marks the field as required                                                                                 |
| `label`       | `string`  |                             | Field label text                                                                                            |
| `viewMode`    | `boolean` | `false`                     | Display as plain text instead of interactive input                                                          |
| `emptyText`   | `string`  |                             | Text shown in view mode when the field is empty                                                             |
| `emptyValue`  | `any`     | `null`                      | Value written to the store when the field is cleared                                                        |
| `inputType`   | `string`  | `"text"`                    | HTML input type. Use `"password"` for password fields                                                       |
| `reactOn`     | `string`  | `"change input blur enter"` | Events that trigger value updates. Options: `"input"`, `"change"`, `"enter"`, `"blur"`. Separate with space |

### Validation

| Property                       | Type      | Default                                  | Description                                               |
| ------------------------------ | --------- | ---------------------------------------- | --------------------------------------------------------- |
| `minLength`                    | `number`  |                                          | Minimum allowed text length                               |
| `maxLength`                    | `number`  |                                          | Maximum allowed text length                               |
| `minLengthValidationErrorText` | `string`  | `"Enter {[{0}-{1}]} more character(s)."` | Error message when text is too short                      |
| `maxLengthValidationErrorText` | `string`  | `"Use {0} characters or fewer."`         | Error message when text is too long                       |
| `validationRegExp`             | `RegExp`  |                                          | Regular expression for validating the input               |
| `validationErrorText`          | `string`  | `"The entered value is not valid."`      | Error message when regex validation fails                 |
| `trim`                         | `boolean` | `false`                                  | Trims whitespace before storing and validating            |
| `error`                        | `string`  |                                          | Custom error message. Field is marked invalid if set      |
| `visited`                      | `boolean` |                                          | If `true`, shows validation errors immediately            |
| `validationMode`               | `string`  | `"tooltip"`                              | How to show errors: `"tooltip"`, `"help"`, `"help-block"` |
| `validationParams`             | `object`  |                                          | Additional params passed to `onValidate`                  |

### Appearance

| Property          | Type            | Default | Description                                                |
| ----------------- | --------------- | ------- | ---------------------------------------------------------- |
| `icon`            | `string/object` |         | Icon on the left side. Can include `onClick` and `tooltip` |
| `showClear`       | `boolean`       | `false` | Shows a clear button when the field has a value            |
| `hideClear`       | `boolean`       | `false` | Opposite of `showClear`                                    |
| `alwaysShowClear` | `boolean`       | `false` | Shows clear button even when field is required             |
| `tooltip`         | `string/object` |         | Tooltip text or configuration                              |
| `inputStyle`      | `string/object` |         | CSS styles applied to the input element                    |
| `inputClass`      | `string`        |         | CSS class applied to the input element                     |
| `inputAttrs`      | `object`        |         | Additional HTML attributes for the input element           |
| `asterisk`        | `boolean`       | `false` | Appends asterisk to label for required fields              |

### Behavior

| Property           | Type      | Default | Description                                         |
| ------------------ | --------- | ------- | --------------------------------------------------- |
| `autoFocus`        | `boolean` | `false` | Automatically focuses the field on mount            |
| `tabOnEnterKey`    | `boolean` | `false` | Moves focus to the next field when Enter is pressed |
| `trackFocus`       | `boolean` | `false` | Adds `cxs-focus` CSS class when input is focused    |
| `focused`          | `boolean` |         | Bound value updated when field gains/loses focus    |
| `tabIndex`         | `string`  |         | Custom tab index                                    |
| `keyboardShortcut` | `string`  |         | Keyboard shortcut to focus the field                |
| `id`               | `string`  |         | HTML id attribute for the input                     |

### Callbacks

| Property     | Description                                                                                       |
| ------------ | ------------------------------------------------------------------------------------------------- |
| `onFocus`    | `(e, instance) => void` - Called when field receives focus                                        |
| `onBlur`     | `(e, instance) => void` - Called when field loses focus                                           |
| `onKeyDown`  | `(e, instance) => boolean` - Return `false` to prevent default                                    |
| `onValidate` | `(value, instance, validationParams) => string` - Return error message or `false` to clear errors |