Form

Form & Input
stable

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.

Anatomy of OrigamFormSchematic of the Form component with 3 numbered internal parts. __content (#default slot — form fields) __details (OrigamMessages — error / hint) __actions (#actions slot) 1 2 3
Anatomy of <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
element with novalidate (prevents browser default validation). Handles @submit and @reset natively.
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.

disabled
boolean
false
Disables all child input fields. Injected as IFormProvide.isDisabled.
fastFail
boolean
false
When true, stops validating subsequent fields after the first error. Useful for long forms where early errors should block submission.
readonly
boolean
false
Makes all child input fields read-only. Injected as IFormProvide.isReadonly.
modelValue
boolean | 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.
rules
Array<any>
Form-level validation rules. Run on submit; errors appear in the __details section.
errorMessages
Array<string> | string
Pre-set error messages displayed in the form details zone (e.g. server-side errors after submit).
hint
string
Helper text shown in the form details zone when no error is present.
messages
Array<string> | string
Informational messages displayed in the form details zone.
scrollToError
boolean | ScrollIntoViewOptions
false
Automatically scrolls to the first field in error on submit. Pass a ScrollIntoViewOptions object to customise the scroll behaviour.
id
string
class
string | Array<string> | object
style
string | Array<string> | object | StyleValue
fontSize
TFontSize
fontWeight
TFontWeight
lineHeight
TLineHeight
letterSpacing
TLetterSpacing

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.

@submit
any
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.
@reset
any
Fired when the form is reset (via the native reset event or the exposed reset() method).
@update:modelValue
any
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

Interactions clavier
ToucheAction
Enter (on submit button)Submits the form when focus is on a [type=submit] button inside the form.
EscapeNo 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.

Source
dimension
var(--origam-space---4)
Top margin of the actions zone (16px).
dimension
var(--origam-space---2)
Gap between action buttons (8px).
dimension
var(--origam-font__size---sm)
Message text font size (0.75rem).
dimension
22px
Minimum height of the message zone.
color
var(--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

vue

Server-side errors

vue