Text Field

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

Import

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

ts
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.

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

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

Example

Favorite fruit

Usage

Default value

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

Favorite fruit

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

tsx
<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.

tsx
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>
		</>
	);
}

tsx
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

tsx
<TextField>
	<TextField.Label>Favorite fruit</TextField.Label>
	<TextField.TextArea />
</TextField>

tsx
<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

tsx
<TextField>
	<TextField.Label>Favorite fruit</TextField.Label>
	<TextField.TextArea autoResize />
</TextField>

tsx
<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.

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

tsx
<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.

tsx
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>
	);
}

tsx
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.

tsx
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>
	);
}

tsx
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` The controlled value of the text field to check.
defaultValue	`string` The default value when initially rendered. Useful when you do not need to control the value.
onChange	`(value: string) => void` Event handler called when the value of the textfield changes.
name	`string` The name of the text field, used when submitting an HTML form. See MDN.
validationState	`'valid' \| 'invalid'` Whether the text field should display its "valid" or "invalid" visual styling.
required	`boolean` Whether the user must fill the text field before the owning form can be submitted.
disabled	`boolean` Whether the text field is disabled.
readOnly	`boolean` 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` Whether the textarea should adjust its height when the value changes.
submitOnEnter	`boolean` Whether the form should be submitted when the user presses the enter key.

TextField.ErrorMessage

Prop	Description
forceMount	`boolean` 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`