# Text Field

A text input that allow users to input custom text entries with a keyboard.

## Import

```
Copyts
import { TextField } from "@kobalte/core/text-field";
// or
import { Root, Label, ... } from "@kobalte/core/text-field";
// or (deprecated)
import { TextField } from "@kobalte/core";
```

```
Copyts
import { TextField } from "@kobalte/core/text-field";
// or
import { Root, Label, ... } from "@kobalte/core/text-field";
// or (deprecated)
import { TextField } from "@kobalte/core";
```

## Features

- Built with a native `<input>` or `<textarea>` element.
- Visual and ARIA labeling support.
- Required and invalid states exposed to assistive technology via ARIA.
- Support for description and error message help text linked to the input via ARIA.
- Syncs with form reset events.
- Can be controlled or uncontrolled.

## Anatomy

The text field consists of:

- **TextField**: The root container for the text field.
- **TextField.Label**: The label that gives the user information on the text field.
- **TextField.Input**: The native HTML input of the text field, used for single line text.
- **TextField.TextArea**: The native HTML textarea of the text field, used for multiline text.
- **TextField.Description**: The description that gives the user more information on the text field.
- **TextField.ErrorMessage**: The error message that gives the user information about how to fix a validation error on the text field.

```
Copytsx
<TextField>
	<TextField.Label />
	<TextField.Input /> {/* or <TextField.TextArea /> */}
	<TextField.Description />
	<TextField.ErrorMessage />
</TextField>
```

```
Copytsx
<TextField>
	<TextField.Label />
	<TextField.Input /> {/* or <TextField.TextArea /> */}
	<TextField.Description />
	<TextField.ErrorMessage />
</TextField>
```

## Example

Favorite fruit

index.tsxstyle.css

```
Copytsx
import { TextField } from "@kobalte/core/text-field";
import "./style.css";

function App() {
  return (
    <TextField class="text-field">
      <TextField.Label class="text-field__label">Favorite fruit</TextField.Label>
      <TextField.Input class="text-field__input" />
    </TextField>
  );
}
```

```
Copytsx
import { TextField } from "@kobalte/core/text-field";
import "./style.css";

function App() {
  return (
    <TextField class="text-field">
      <TextField.Label class="text-field__label">Favorite fruit</TextField.Label>
      <TextField.Input class="text-field__input" />
    </TextField>
  );
}
```

## Usage

### Default value

An initial, uncontrolled value can be provided using the `defaultValue` prop.

Favorite fruit

```
Copytsx
<TextField defaultValue="Apple">
	<TextField.Label>Favorite fruit</TextField.Label>
	<TextField.Input />
</TextField>
```

```
Copytsx
<TextField defaultValue="Apple">
	<TextField.Label>Favorite fruit</TextField.Label>
	<TextField.Input />
</TextField>
```

### Controlled value

The `value` prop can be used to make the value controlled. The `onChange` event is fired when the user type into the input and receive the new value.

Favorite fruit

Your favorite fruit is: Apple.

```
Copytsx
import { createSignal } from "solid-js";

function ControlledExample() {
	const [value, setValue] = createSignal("Apple");

	return (
		<>
			<TextField value={value()} onChange={setValue}>
				<TextField.Label>Favorite fruit</TextField.Label>
				<TextField.Input />
			</TextField>
			<p>Your favorite fruit is: {value()}.</p>
		</>
	);
}
```

```
Copytsx
import { createSignal } from "solid-js";

function ControlledExample() {
	const [value, setValue] = createSignal("Apple");

	return (
		<>
			<TextField value={value()} onChange={setValue}>
				<TextField.Label>Favorite fruit</TextField.Label>
				<TextField.Input />
			</TextField>
			<p>Your favorite fruit is: {value()}.</p>
		</>
	);
}
```

### Multiline

Use the `TextField.TextArea` component instead of `TextField.Input` to create a multiline text field.

Favorite fruit

```
Copytsx
<TextField>
	<TextField.Label>Favorite fruit</TextField.Label>
	<TextField.TextArea />
</TextField>
```

```
Copytsx
<TextField>
	<TextField.Label>Favorite fruit</TextField.Label>
	<TextField.TextArea />
</TextField>
```

In addition, the `autoResize` prop can be used to make the textarea height adjust to it's content. Try typing in the text field below to see it in action.

Favorite fruit

```
Copytsx
<TextField>
	<TextField.Label>Favorite fruit</TextField.Label>
	<TextField.TextArea autoResize />
</TextField>
```

```
Copytsx
<TextField>
	<TextField.Label>Favorite fruit</TextField.Label>
	<TextField.TextArea autoResize />
</TextField>
```

### Description

The `TextField.Description` component can be used to associate additional help text with a text field.

Favorite fruit

Choose the fruit you like the most.

```
Copytsx
<TextField>
	<TextField.Label>Favorite fruit</TextField.Label>
	<TextField.Input />
	<TextField.Description>Choose the fruit you like the most.</TextField.Description>
</TextField>
```

```
Copytsx
<TextField>
	<TextField.Label>Favorite fruit</TextField.Label>
	<TextField.Input />
	<TextField.Description>Choose the fruit you like the most.</TextField.Description>
</TextField>
```

### Error message

The `TextField.ErrorMessage` component can be used to help the user fix a validation error. It should be combined with the `validationState` prop to semantically mark the text field as invalid for assistive technologies.

By default, it will render only when the `validationState` prop is set to `invalid`, use the `forceMount` prop to always render the error message (ex: for usage with animation libraries).

Favorite fruit

Hmm, I prefer apples.

```
Copytsx
import { createSignal } from "solid-js";

function ErrorMessageExample() {
	const [value, setValue] = createSignal("Orange");

	return (
		<TextField
			value={value()}
			onChange={setValue}
			validationState={value() !== "Apple" ? "invalid" : "valid"}
		>
			<TextField.Label>Favorite fruit</TextField.Label>
			<TextField.Input />
			<TextField.ErrorMessage>Hmm, I prefer apples.</TextField.ErrorMessage>
		</TextField>
	);
}
```

```
Copytsx
import { createSignal } from "solid-js";

function ErrorMessageExample() {
	const [value, setValue] = createSignal("Orange");

	return (
		<TextField
			value={value()}
			onChange={setValue}
			validationState={value() !== "Apple" ? "invalid" : "valid"}
		>
			<TextField.Label>Favorite fruit</TextField.Label>
			<TextField.Input />
			<TextField.ErrorMessage>Hmm, I prefer apples.</TextField.ErrorMessage>
		</TextField>
	);
}
```

### HTML forms

The text field `name` prop can be used for integration with HTML forms.

Favorite fruit

ResetSubmit

```
Copytsx
function HTMLFormExample() {
	const onSubmit = (e: SubmitEvent) => {
		// handle form submission.
	};

	return (
		<form onSubmit={onSubmit}>
			<TextField name="favorite-fruit">
				<TextField.Label>Favorite fruit</TextField.Label>
				<TextField.Input />
			</TextField>
			<div>
				<button type="reset">Reset</button>
				<button type="submit">Submit</button>
			</div>
		</form>
	);
}
```

```
Copytsx
function HTMLFormExample() {
	const onSubmit = (e: SubmitEvent) => {
		// handle form submission.
	};

	return (
		<form onSubmit={onSubmit}>
			<TextField name="favorite-fruit">
				<TextField.Label>Favorite fruit</TextField.Label>
				<TextField.Input />
			</TextField>
			<div>
				<button type="reset">Reset</button>
				<button type="submit">Submit</button>
			</div>
		</form>
	);
}
```

## API Reference

### TextField

`TextField` is equivalent to the `Root` import from `@kobalte/core/text-field` (and deprecated `TextField.Root`).

| Prop | Description |
| --- | --- |
| value | `string`<br> The controlled value of the text field to check. |
| defaultValue | `string`<br> The default value when initially rendered. Useful when you do not need to control the value. |
| onChange | `(value: string) => void`<br> Event handler called when the value of the textfield changes. |
| name | `string`<br> The name of the text field, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| validationState | `'valid' | 'invalid'`<br> Whether the text field should display its "valid" or "invalid" visual styling. |
| required | `boolean`<br> Whether the user must fill the text field before the owning form can be submitted. |
| disabled | `boolean`<br> Whether the text field is disabled. |
| readOnly | `boolean`<br> Whether the text field items can be selected but not changed by the user. |

| Data attribute | Description |
| --- | --- |
| data-valid | Present when the text field is valid according to the validation rules. |
| data-invalid | Present when the text field is invalid according to the validation rules. |
| data-required | Present when the user must fill the text field before the owning form can be submitted. |
| data-disabled | Present when the text field is disabled. |
| data-readonly | Present when the text field is read only. |

`TextField.Label`, `TextField.Input`, `TextField.TextArea`, `TextField.Description` and `TextField.ErrorMesssage` share the same data-attributes.

### TextField.TextArea

| Prop | Description |
| --- | --- |
| autoResize | `boolean`<br> Whether the textarea should adjust its height when the value changes. |
| submitOnEnter | `boolean`<br> Whether the form should be submitted when the user presses the enter key. |

### TextField.ErrorMessage

| Prop | Description |
| --- | --- |
| forceMount | `boolean`<br> Used to force mounting when more control is needed. Useful when controlling animation with SolidJS animation libraries. |

## Rendered elements

| Component | Default rendered element |
| --- | --- |
| `TextField` | `div` |
| `TextField.Label` | `label` |
| `TextField.Input` | `input` |
| `TextField.TextArea` | `textarea` |
| `TextField.Description` | `div` |
| `TextField.ErrorMessage` | `div` |

Previous[←Tabs](https://kobalte.dev/docs/core/components/tabs)Next[Time Field→](https://kobalte.dev/docs/core/components/time-field)