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.
<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
| Attribute | Property | Type | Default | Description |
|---|
label | label | string | '' | The visible label above the field. Required: it is also the field's accessible name. |
type | type | 'text' | 'email' | 'password' | 'search' | 'tel' | 'url' | 'text' | The kind of text. Sets the keyboard on phones and the built-in validation. |
value | value | string | '' | The current text. |
placeholder | placeholder | string | '' | Example text shown while the field is empty. Never a substitute for label. |
help-text | helpText | string | '' | Help text under the field, such as the expected format. |
error | error | string | '' | A custom error message. While set, the field is invalid and shows it. |
readonly | readonly | boolean | false | The text can be selected and submitted, but not changed. |
minlength | minLength | number | — | The minimum number of characters. |
maxlength | maxLength | number | — | The maximum number of characters. |
pattern | pattern | string | '' | A regular expression the whole value must match. |
autocomplete | autocomplete | string | '' | A hint for the browser's autofill, such as email or name. |
name | name | string | '' | Submitted with the form as name=value. |
disabled | disabled | boolean | false | Disables the control. It can't be focused, changed or submitted. |
required | required | boolean | false | The 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
| Event | Description |
|---|
input | The native input event, on every keystroke. Read event.target.value. |
change | When the user commits a change, by leaving the field or pressing Enter. |
Slots
| Slot | Description |
|---|
start | An icon or prefix inside the field, before the text. |
end | An icon or suffix inside the field, after the text. |
Methods
| Method | Description |
|---|
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 property | Type | Description |
|---|
--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. |
| Part | Description |
|---|
::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
| Key | Does |
|---|
| Tab | Moves 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.