project-form-patterns

aghub Form Patterns

Follow these rules when building forms in this project.

Source of Truth

• Check the official docs first, not memory and not bundled/local docs, when form behavior is in question.
• For HeroUI, prefer the official site:
  • https://v3.heroui.com/docs/react/components/form
  • https://v3.heroui.com/docs/react/components/text-field
  • https://v3.heroui.com/docs/react/components/field-error
  • https://v3.heroui.com/docs/react/components/select
• Use local skill docs only as a convenience after confirming the official API.

Default Stack

• Prefer react-hook-form for non-trivial forms.
• Use Controller for HeroUI Select and any custom controlled widgets.
• Keep one form state. Do not create a second derived validation state unless there is a concrete need the form library cannot express.

Validation Behavior

• When RHF controls validation, set HeroUI form fields to validationBehavior="aria".
• Do not rely on HeroUI/native validation defaults together with RHF. Native validation can steal focus and submission flow while bypassing the error UI you expect from RHF.
• Let RHF own validation rules and submission blocking.

Error Rendering

• For HeroUI text fields, use:
  • isInvalid={Boolean(fieldState.error)}
  • Conditionally render <FieldError>{fieldState.error.message}</FieldError> inside the same TextField.
• Do not invent unsupported props. In particular, do not assume TextField supports an errorMessage prop.
• Keep the official anatomy:

<TextField isInvalid={Boolean(fieldState.error)} validationBehavior="aria">
	<Label>Name</Label>
	<Input {...inputProps} />
	{fieldState.error && <FieldError>{fieldState.error.message}</FieldError>}
</TextField>

• For non-form or custom composite controls, prefer HeroUI ErrorMessage instead of hand-rolled error text.
• Use ErrorMessage for collection-style or custom editors that are not true form fields, including key/value editors, tag selectors, and similar composite controls.