Field
A field gives one form control a visible label, help text, and an error message, and names the control for screen readers.
<tk-field label="Email address" helper="We only use this for the receipt"> <tk-input type="email" name="email" autocomplete="email"></tk-input> </tk-field>
Anatomy
| Part | What it is |
|---|---|
tk-field |
the wrapper; no Tab stop and no form value of its own |
| label | the label text and, when required, an asterisk |
| help text | the helper text, between the label and the control |
| default slot | the control, exactly one |
| error | the error message with an icon, under the control |
The Field draws the label, help text, and error from its attributes. The control keeps its value, its Tab stop, and its keyboard.
States
<tk-field label="Company name" required> <tk-input name="company"></tk-input> </tk-field> <tk-field label="Email address" required error="Enter an email address, like name@example.com"> <tk-input type="email" name="email" value="ada@"></tk-input> </tk-field>
<tk-field label="Username" helper="Usernames can't be changed" disabled> <tk-input name="username" value="ada"></tk-input> </tk-field>
required: adds an asterisk after the label and makes the control required. The asterisk is gray, not red: an empty required field hasn't failed yet.error: shows the message under the control, turns its border red, and marks it invalid. Removeerrorto clear it.disabled: the control can't be focused or edited. The label and help text stay readable, so the help text can say why the field is locked.- Set
requiredanddisabledon the Field, not on the control. The Field overwrites the control's own values.
The Field doesn't validate. You decide when to set error and what it says.
Label, help text, and errors
<tk-field label="Card number" helper="The 16 digits on the front of your card"> <tk-input inputmode="numeric" name="card" autocomplete="cc-number"></tk-input> </tk-field>
<tk-input aria-label="Filter by name"></tk-input>
- The Field names the control from
label, and adds the help text and error to its description. Clicking the label moves focus into the control. - Without a visible label, skip the Field and set
aria-labelon the control. Use it only when the purpose is clear from what's around the field. - Every control needs one or the other. A placeholder is never a label.
- A
Search field names itself "Search" on its own; inside a Field, the Field's label replaces that name.
When to use
- Wrap a control in a Field whenever it needs a visible label. It works with
Input ,Textarea ,Number input ,OTP input ,Phone input ,Search field ,Select ,Combobox ,Multiselect ,Date picker , andTime picker . A form is a stack of Fields. - One Field holds one control.
- Don't wrap a
Checkbox ,Radio , orSwitch . Their label sits beside them and names them; the Field ignores them and logs a console warning. - For a set of radios or checkboxes, use a
radio group orcheckbox group . The group has its own label.
Content
- Label: name what you're asking for. Short, sentence case, no colon: "Email address", "Country".
- Help text: one short line, such as a format or where to find the value. Nothing essential, no links.
- Error: say what happened and how to fix it, in the label's words: "Enter your full name". No "please", "sorry", or "invalid".
- Required fields: if a form marks them with asterisks, add one line near the top: "* indicates a required field".
More in
Do / Don't
| ✅ Do | ❌ Don't |
|---|---|
Set label on the Field |
Expect a bare control to show a label |
| Put one control in each Field | Wrap a checkbox, radio, or switch |
Set required and disabled on the Field |
Set them on a control inside a Field |
| Say in the help text why a field is disabled | Disable a field with no explanation |
| Give every control a name | Use a placeholder as the label |
Related
Input : the single-line control you'll wrap most often.Checkbox ,Radio , andSwitch : controls that label themselves, without a Field.Errors : how to write error messages.
API
Attributes
| Attribute | Type | Default | What it does |
|---|---|---|---|
label |
string | '' |
the visible label and the control's accessible name; required |
helper |
string | — | help text under the label; added to the control's description |
error |
string | — | the error message; turns the border red and marks the control invalid |
required |
boolean | false |
shows the asterisk and sets required on the control |
disabled |
boolean | false |
sets disabled on the control; the label and help text stay readable |
value, name, placeholder, and size go on the control, not the Field.
Slots
| Slot | Content |
|---|---|
| default | one control, such as tk-input or tk-select |
Events
No events of its own. The control's input and change events pass through.
Methods
focus(): moves focus into the control.
Tokens
| Role | Token |
|---|---|
| label | text/default, medium weight |
| asterisk and help text | text/secondary |
| error message and icon | text/error, icon/error |
| label to help text | space-4 |
| help text or label to control | space-8 |
| control to error | space-4 |
The control brings its own box tokens; its error border is border/error. Values per
theme:
Accessibility
Built in:
- The Field names the control's inner element, so screen readers read the label once.
- The help text and error are read as the control's description, and
errorsetsaria-invalid. - The error message starts with a hidden "Error:" for screen readers.
- The asterisk is hidden from screen readers; the control announces "required".
- Clicking the label focuses the control.
Your part:
- Give every control a name: a Field
label, oraria-labelon the control. - Errors are read when the control gets focus, not as they appear. If you validate on submit, show a summary at the top and move focus to it.
- If a field is disabled, say why in the help text.
The Field adds no keys; the control owns the keyboard. In browsers without ARIA element reflection (before 2025), screen readers may not read the help text and error.