PettyUI/.firecrawl/kobalte.dev-docs-core-components-text-field.md

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

Previous←TabsNextTime Field→