Input

WHEN TO USE

• You need one line of typed input: text, email, number, password, url or tel. type selects the native input type, which is what gives mobile keyboards and browser autofill something to work with.
• The field belongs to a form whose data you read with FormData. Set name and the value is carried through form-associated custom element internals.
• The field needs helper text, an error, a required marker or a character counter — all four are built in and positioned for you.

WHEN NOT TO USE

• The user needs to write more than a line or two. A single-line field with a long value hides most of what has been typed.USE TEXTAREA →
• The value comes from a fixed set of options rather than free typing. A text field with a validation message is a worse version of a picker.USE SELECT →
• The user is filtering or querying a list rather than filling in a field — that pattern wants its own affordance and clear control.USE SEARCH →
• You want a number the user nudges up and down rather than types, such as a quantity.USE INPUT-STEPPER →

DO

• Set isError whenever you set errorNote. The error block only renders when isError is true, so an error string on its own displays nothing at all.
• Prefer hideLabel over omitting label when the layout has no room for it. The <label for> is still rendered and still associated — it is only visually hidden, and the required asterisk is relocated so it stays visible.
• Use fieldNote for the rule the user needs BEFORE typing ("At least 8 characters"), and errorNote for what went wrong after.
• Set maxLength when there is a real limit; it renders both the native maxlength and a live n/max counter, and drive the counter with maxLengthValue.

DON’T

• Don't rely on the error note being announced. Only the FIELD note is given the aria-describedby id — the error block is rendered without it, so a screen-reader user reaches the error only by browsing the field, not on focus.
• Don't expect isError to set aria-invalid. The component renders no aria-invalid at all, so the invalid state is conveyed visually and through the note, not through the accessibility tree.
• Don't use placeholder as the label. It disappears on the first keystroke, is not associated with the field, and leaves the user with no way back to the question.
• Don't set autoComplete on a password field expecting it to apply — the component forces autocomplete="off" whenever type="password".
• Don't stack isRequired and isOptional on the same field. They render two contradictory markers, an asterisk and an "(Optional)" note.