Forms and validation

Forms are everywhere in Home Assistant: setting up an integration, editing an automation, changing the settings of an entity. They all follow the same pattern, so people know where to look for the label, the hint, and the problem.

Use this pattern whenever you ask people for one or more values. For a single setting that takes effect right away, like turning a feature on or off, a switch on its own is enough.

Most forms in the frontend are built with the form component. You describe the fields, and it picks the right control for each value through a selector: a text field for a name, a picker for an entity, a switch for a yes or no. Setup and options dialogs of integrations are rendered the same way. That is why they all look and behave alike.

• Every field has a visible label. A placeholder is not a label: it disappears as soon as someone starts typing.
• When a field needs explaining, add helper text. It sits below the field. In ha-form, it comes from computeHelper.
• Use the established field layout and the shared components, not a raw input or a control you built yourself.

• A required field shows a * after its label.
• Make fields optional when that makes sense, and give them a sensible default. A good default helps, without getting in the way of people who want something else.

A field is checked when the form is submitted. A text input with auto-validate is checked as soon as people leave the field instead.

When a value is not valid:

• The field is marked as invalid, and its validation message takes the place of the helper text.
• In ha-form, an error about one field shows right above that field. An error about the whole form, like a failed connection, shows at the top.
• Focus moves to the first field with a problem, so keyboard and screen reader users land right on it.

Errors are shown as an alert, so they have an icon and text, not only a red color. For how to word them, see Messages.

• The form gets focus when the dialog opens: give it the autofocus attribute.
• The main action, like Save, sits at the bottom right, next to Cancel.
• Once someone has changed something, the dialog does not close with Escape or by selecting outside of it. See Confirmations and undo.

Form markup should not make password managers mistake a field for something it is not.

• The label of a field is its accessible name. Keep it, also when space is tight.
• An invalid text input sets aria-invalid, and its validation message is announced.
• See Labels and accessible names for the WCAG side.

• Form and selector
• Text input and textarea
• Switch, select box, and select menu
• Entity picker, device picker, and area picker
• Alert, for errors and warnings

Use ha-form with a schema. computeLabel, computeHelper, and computeError turn names and error keys into translated text. Set error to an object keyed by field name, with base for the form as a whole. warning works the same way, without base. The form page has the details.