UI components · Forms
Form Item
Also called: Form field, Field, Form group, Form row
One field unit in a form. The field label, the input control, helper text, and the error message together make up the basic building block of a form.
Click “Labeled” to see what each part is called, or “Anti-pattern” to see the most common mistake.
How to tell AI
Swap in your own content firstMake every field in this form a consistent form item. Label on top (14px, dark gray, a label tag linked to the control with for), with a red asterisk after required labels. Controls are 36px tall and full width. Under each control, a line of 12px gray helper text. When validation fails, swap it for a red error message and give the control a red border. The message should say what's wrong and how to fix it (for example "Phone number must be 10 digits"). Put 20px between form items, and reserve a fixed height for the helper/error line so the layout doesn't jump when an error appears.
Send to
01Decide
Does your content look like this?
Check both columns to confirm Form Item is what you need.
Use Form Item when
- Any field users fill in, like sign-up, checkout, settings, and create or edit screens in admin apps
- When a field needs a note about its format or purpose right next to the control
- When validation errors need to show up right under the specific field
Pick something else when
Info that's only displayed and can't be edited. Use a description list, not a row of disabled inputs.
A single search box at the top of a page. Just use a search box, no label or helper text needed.
A row of query conditions above a table. A filter bar is more compact.
Not sure? Upload a screenshot and page analysis will check which layout each block should use.
02Pitfalls
Common misuse
It looks like it works, but it makes things harder for users.
- 01
Using only placeholder text as the field name, so once users start typing they forget what the field was for
The wireframe below shows this case. The red dashed box marks the problem.The wireframe on the right shows this case. The red dashed box marks the problem.
- 02
Piling all error messages at the top of the form, so users have to hunt back and forth for the field that's wrong
- 03
Uneven spacing between labels, controls, and helper text, so you can't tell which note belongs to which input
03Spot it
How to spot it
Look at the overall structure first, then check a few features you can spot at a glance.
Structure
A field label (a label, optionally with a required marker and a hint icon), the input control, helper text, and an error message. The label can sit above or to the left of the control.
PartsClick one to highlight it in the wireframe above
04Explained
In detail
A form item is one row (or cell) in a form. The field label sits above or to the left, the control (an input, select, radio buttons, and so on) sits in the middle, and a line of gray helper text sits below, replaced by a red error message when something's wrong. Required fields get an asterisk or "Required" next to the label. A form is just a lot of form items lined up.
How it differs from an Input: the input is only the box you type in. A form item is the box plus its label, helper text, and error, all as one unit. How it differs from a Form: the form is the whole thing and handles grouping, submitting, and overall validation. A form item only handles one field. Telling the AI "put the form item's error message below the control" is more precise than "add some red text under the input."
Use a label tag for the field name and connect it to the control, so clicking the label focuses the control and screen readers can read it. Don't use placeholder text in place of a label. Put the error right under the control that failed and say how to fix it. If helper text and errors share the same spot, reserve that line's height so content below doesn't jump when an error shows up.
Developer infoTerm ID, DOM cues, match priority
- Term ID
component-form-item- DOM selectors
The extension matches these CSS selectors when it inspects a page locally (tags, ARIA roles, common component library classes).
.ant-form-item.el-form-item[class*="MuiFormControl-root"].arco-form-item.t-form__item.n-form-item[data-slot="form-item"].form-group.mb-3:has(> .form-label)div:has(> label):has(> input, > select, > textarea)
- Class keywords
Class names, ids and data-testid are split into words and matched in order, so page-header, PageHeader_root__x7a and pageHeader all become page, header.
form-itemform-fieldform-groupform-rowfield-groupfield-rowerror-messagefield-error
- Component names
React / Vue component names read in development mode. Case-insensitive; library prefixes such as El, Ant and Mui are dropped.
FormItemFormFieldFormControlFormGroupField
- Structure
Computed from how the element is laid out and styled. It only adds to the score and never decides on its own.
form controls
- Priority
- 2 · when several match at the same level, the higher priority wins
- Version
- v2 · updated Sep 30, 2026