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
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<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
All props accepted by this component, with their type, default value and 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
Content slots exposed by this component.
- #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
Events emitted by this component.
- @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
Exposed members
Properties and methods accessible via template ref (defineExpose). Use them for programmatic control.
- <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.
Customisation
CSS variables
CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.
- 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
Accessibility
ARIA roles, keyboard navigation and focus management. Sourced from the real component template.
Keyboard interactions
| Key | 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.
Foundation
Design tokens
Excerpt from this component's token declarations — the --origam-<component>---<property> variables, declared in its hand-maintained token sheet with no build step.
- 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.
Interactive
Playground
Edit props live and see the component update in real time. The generated code snippet updates as you change values.
Rendering the live preview…
Usage
Examples
Ready-to-paste code snippets for your templates.
Basic validated form
Server-side errors