Vastu

Text field <va-text-field>

Collects a short piece of text, such as a name, an email address or a search term.

When to use it

Use it
For short, free-form text: names, email addresses, search terms, codes.
Don't use it
For long text, or for picking from a fixed set of options.
Use instead
A textarea for long text; a select or radio group for fixed options.

Examples

Label, help and placeholder

Every field has a visible label. Help text says what format to use; a placeholder only gives an example.

<va-text-field label="Full name" autocomplete="name"></va-text-field>
<va-text-field label="Username" help-text="Letters and numbers only, 3 to 20 characters." placeholder="e.g. ada99" minlength="3" maxlength="20" pattern="[A-Za-z0-9]+"></va-text-field>

Validation in a form

Errors show after the user leaves the field or submits, never while they type.

Subscribe
<form>
  <va-text-field label="Email address" name="email" type="email" required autocomplete="email"></va-text-field>
  <va-button type="submit">Subscribe</va-button>
</form>

Custom error, read-only and disabled

Set error to show a message from your own validation, such as a server check.

<va-text-field label="Coupon code" value="SPRING" error="This code has expired."></va-text-field>
<va-text-field label="Account ID" value="ACC-20817" readonly></va-text-field>
<va-text-field label="Company" disabled help-text="Only an admin can change this."></va-text-field>

Install and import

npm install @firstprateek/vastu @firstprateek/vastu-tokens
import '@firstprateek/vastu-tokens/lekha.css'; // once per page
import '@firstprateek/vastu/text-field';

API

Attributes and properties

AttributePropertyTypeDefaultDescription
labellabelstring''The visible label above the field. Required: it is also the field's accessible name.
typetype'text' | 'email' | 'password' | 'search' | 'tel' | 'url''text'The kind of text. Sets the keyboard on phones and the built-in validation.
valuevaluestring''The current text.
placeholderplaceholderstring''Example text shown while the field is empty. Never a substitute for label.
help-texthelpTextstring''Help text under the field, such as the expected format.
errorerrorstring''A custom error message. While set, the field is invalid and shows it.
readonlyreadonlybooleanfalseThe text can be selected and submitted, but not changed.
minlengthminLengthnumber—The minimum number of characters.
maxlengthmaxLengthnumber—The maximum number of characters.
patternpatternstring''A regular expression the whole value must match.
autocompleteautocompletestring''A hint for the browser's autofill, such as email or name.
namenamestring''Submitted with the form as name=value.
disableddisabledbooleanfalseDisables the control. It can't be focused, changed or submitted.
requiredrequiredbooleanfalseThe control must have a value before its form can be submitted.
—form (read-only)HTMLFormElement | null—The form this control belongs to, if any.
—validity (read-only)ValidityState—The control's validity state, as on native controls.
—validationMessage (read-only)string—The message the browser shows when the control is invalid, or an empty string.

Events

EventDescription
inputThe native input event, on every keystroke. Read event.target.value.
changeWhen the user commits a change, by leaving the field or pressing Enter.

Slots

SlotDescription
startAn icon or prefix inside the field, before the text.
endAn icon or suffix inside the field, after the text.

Methods

MethodDescription
select()Selects all the text in the field.
checkValidity()Returns true if the control is valid; otherwise fires invalid and returns false.
reportValidity()Like checkValidity(), but also shows the browser's message to the user.

Styling

Components read the brand's tokens. To adjust one component, set its custom properties or style its parts.

Custom propertyTypeDescription
--va-text-field-bg<color>Background colour of the field.
--va-text-field-border<color>Border colour of the field.
--va-text-field-border-invalid<color>Border colour while the field shows an error.
--va-text-field-radius<length>Corner radius of the field.
--va-text-field-height<length>Minimum height of the field.
PartDescription
::part(label)The visible label.
::part(field)The box around the input and its icons.
::part(input)The native input.
::part(help)The help text.
::part(error)The error message.

Accessibility

Role
textbox
Accessible name
The label attribute, shown above the field. Every text field needs one.
Note
Help text and the error message are linked with aria-describedby; the error also sets aria-invalid.
Note
Errors appear after the user leaves the field or submits the form, not while they type.

Keyboard

KeyDoes
TabMoves focus to the next control.

Every row on this page is checked by contract tests generated from the same manifest, in Chromium, Firefox and WebKit. Read the manifest.