Kobalte.v0.13.7

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

Usage

Default value

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

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.

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.

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.

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.

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

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

PropDescription
valuestring
The controlled value of the text field to check.
defaultValuestring
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.
namestring
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.
requiredboolean
Whether the user must fill the text field before the owning form can be submitted.
disabledboolean
Whether the text field is disabled.
readOnlyboolean
Whether the text field items can be selected but not changed by the user.
Data attributeDescription
data-validPresent when the text field is valid according to the validation rules.
data-invalidPresent when the text field is invalid according to the validation rules.
data-requiredPresent when the user must fill the text field before the owning form can be submitted.
data-disabledPresent when the text field is disabled.
data-readonlyPresent 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

PropDescription
autoResizeboolean
Whether the textarea should adjust its height when the value changes.
submitOnEnterboolean
Whether the form should be submitted when the user presses the enter key.

TextField.ErrorMessage

PropDescription
forceMountboolean
Used to force mounting when more control is needed. Useful when controlling animation with SolidJS animation libraries.

Rendered elements

ComponentDefault rendered element
TextFielddiv
TextField.Labellabel
TextField.Inputinput
TextField.TextAreatextarea
TextField.Descriptiondiv
TextField.ErrorMessagediv
Previous
Tabs
Next
Toast