Form
Form container with centralised validation, global error messaging, accessible submit/reset lifecycle, and an optional scroll-to-first-error behaviour. Wraps any number of Origam input fields and coordinates their validation state.
Structure
Anatomie
Décomposition visuelle de la structure interne du composant avec les appels de classes BEM.
<origam-form> — 3 internal zones. The root ① is a native <form novalidate>. Content ② holds the input fields. Details ③ shows form-level error/hint messages via OrigamMessages.- 1.origam-form
- Root
- 2.origam-form__content
- Wrapper div hosting the #default slot. Contains all field components that register with the form.
- 3.origam-form__details
- Form-level messages zone. Renders OrigamMessages when there are form-level errors or hints. Hidden when no messages are active.
- 4.origam-form__actions
- Actions row. Rendered only when the #actions slot is provided. Flex container with gap and top margin.
API
Props
Toutes les props acceptées par ce composant, avec leur type, valeur par défaut et description.
- disabledbooleanfalse
- Disables all child input fields. Injected as IFormProvide.isDisabled.
- fastFailbooleanfalse
- When true, stops validating subsequent fields after the first error. Useful for long forms where early errors should block submission.
- readonlybooleanfalse
- Makes all child input fields read-only. Injected as IFormProvide.isReadonly.
- modelValueboolean | null
- v-model binding reflecting the overall validity: true = valid, false = invalid, null = not yet validated.
- validateOn
- Controls when child fields trigger validation. Values: 'blur' | 'input' | 'change' | 'submit' | 'lazy' | combinations.
- rulesArray<any>
- Form-level validation rules. Run on submit; errors appear in the __details section.
- errorMessagesArray<string> | string
- Pre-set error messages displayed in the form details zone (e.g. server-side errors after submit).
- hintstring
- Helper text shown in the form details zone when no error is present.
- messagesArray<string> | string
- Informational messages displayed in the form details zone.
- scrollToErrorboolean | ScrollIntoViewOptionsfalse
- Automatically scrolls to the first field in error on submit. Pass a ScrollIntoViewOptions object to customise the scroll behaviour.
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- fontSizeTFontSize
- fontWeightTFontWeight
- lineHeightTLineHeight
- letterSpacingTLetterSpacing
API
Slots
Emplacements de contenu exposés par ce composant.
- #messages
- Replaces the OrigamMessages zone in the __details section.
- #message
- Replaces a single message row inside the messages slot.
- #actions
- Action buttons rendered inside the __actions div below the form content. Receives submit and reset callbacks.
- #default
- Form content. Receives the form helpers (submit, reset, validate, resetValidation) and state (isValid, isValidating, items, errors).
API
Emits
Événements émis par ce composant.
- @submitany
- Fired on form submit. The event is augmented with a Promise that resolves to { valid, errors }. Prevent the default to stop the native form submission.
- @resetany
- Fired when the form is reset (via the native reset event or the exposed reset() method).
- @update:modelValueany
- Fired when the global validity changes.
API
Membres exposés
Propriétés et méthodes accessibles via ref template (defineExpose). Utilisés pour le contrôle programmatique.
- <T extends object>(props: T, exclude?: string[]) => Partial<T>
- Filters and forwards props to child components.
- () => void
- Triggers form validation and submit. Equivalent to clicking a [type=submit] button.
- () => void
- Resets all child fields to their initial value and clears validation errors.
- () => Promise<IFormValidationResult>
- Programmatically validates all registered child fields. Returns { valid, errors }.
- () => void
- Clears all validation errors without resetting field values.
- Ref<boolean | null>
- Current overall validity: true (valid), false (invalid), null (pending).
- Ref<boolean>
- True while async validators are running.
- Ref<IFormField[]>
- All registered child field descriptors (id, validate, reset, resetValidation, isValid, errorMessages).
- ComputedRef<IFieldValidationResult[]>
- Flat list of { id, errorMessages } for all fields currently in error.
- (options?: boolean | ScrollIntoViewOptions) => Promise<void>
- Scrolls to the first .origam-input--error element in the form DOM.
Personnalisation
Variables CSS
Propriétés CSS personnalisées exposées par ce composant. Surchargez-les pour personnaliser sans perdre la compatibilité avec le thème.
- Top margin separating the actions row from the form body.
- Gap between action buttons in the __actions row.
- Font size of form-level messages.
- Minimum height of the details zone. Prevents layout shift when messages appear.
- Message text colour in error state.
- Icon colour in error state.
Inclusion
Accessibilité
Rôles ARIA, navigation clavier et gestion du focus. Sourcé depuis le template réel du composant.
Interactions clavier
| Touche | Action |
|---|---|
| Enter (on submit button) | Submits the form when focus is on a [type=submit] button inside the form. |
| Escape | No built-in behaviour — consumers may bind Escape to call reset() or navigate away. |
Notes
- The form element uses novalidate to suppress browser-native validation bubbles. All validation is handled by Origam components and displayed in field detail zones.
- Form-level messages appear in the __details section via OrigamMessages which carries aria-live="polite" internally. Screen readers announce errors after submit.
- scrollToError (prop) and scrollToFirstError (exposed method) move focus to the first errored field after validation. This is an important accessibility improvement for long forms — screen readers naturally encounter the error context without manual navigation.
- Setting disabled=true injects IFormProvide.isDisabled = true into all descendant fields via provide/inject. No need to set disabled individually on each field.
Fondation
Design tokens
Extrait des tokens de ce composant — les variables --origam-<composant>---<propriété>, déclarées dans sa feuille de tokens tenue à la main, sans étape de build.
- dimensionvar(--origam-space---4)
- Top margin of the actions zone (16px).
- dimensionvar(--origam-space---2)
- Gap between action buttons (8px).
- dimensionvar(--origam-font__size---sm)
- Message text font size (0.75rem).
- dimension22px
- Minimum height of the message zone.
- colorvar(--origam-color__feedback--danger---fgSubtle)
- Error message colour.
Interactif
Playground
Modifiez les props en direct et observez le composant se mettre à jour. Le snippet de code généré suit vos changements.
Rendu de l’aperçu en cours…
Usage
Exemples
Extraits de code prêts à coller dans vos templates.
Basic validated form
Server-side errors