Form

An enhanced native <form> supporting validation and submission of inner fields according to rules.

The data source is each field's value attribute (controlled mode). Fields validated by the form are oas-input / oas-textarea / oas-select / oas-auto-complete / oas-cascader / oas-tree-select / oas-input-number / oas-checkbox / oas-radio with a name (group containers are not involved). oas-input / oas-textarea / oas-input-number do not automatically write back to the value attribute while typing — listen to oas-input / oas-change events in script to sync; oas-select / oas-cascader / oas-tree-select write back by themselves on selection.

Feature Demo

The feature demo area only demonstrates field collection and submission, without validation rules.

Basic Usage

Collect & submit

Submit

Example

Without rules, submission performs no validation and dispatches oas-submit directly, with detail.values carrying the collected results of all fields with a name.

Mixed Controls

Mixed controls

Submit

Example

Validation

The validation area demonstrates rules-declared validation rules and failure feedback.

Validation rules: { required, message, minLength, maxLength, pattern }. On failure, the field is marked aria-invalid (red-bordered input), an error message is shown in red below the field, and oas-validate-fail is dispatched.

Required & Format Validation

Required & format validation

Submit

Example

Length Validation

minLength validation

Submit

Example

Disabled Fields Skip Validation

Disabled fields are not validated

Submit

Example

Submit & Validation-fail Events

submit / validate-fail

Submit

Example

Grid Form Layout

With layout="grid", the form element becomes a 24-column grid and oas-form-item spans columns via span (default 24 = full row); gap controls grid spacing, label-align positions the label (left / right / top, default top), and label-width sets the label column width for left/right. On validation failure, error messages are collected into the oas-form-item error slot (role="alert").

Two-Column Grid with Validation

Two-column grid layout

Submit

Example

label-align & label-width

Switch label-align

Example

Inline Form Layout

With inline, items are laid out horizontally: the label sits on the left of the control (auto-width), controls size to their content, item spacing follows gap (default var(--oas-space-4)), and items wrap when the container is too narrow. Coexists with layout and takes precedence over it; forces label-align to left and label-width to auto. Suited to compact toolbars like login and search.

Inline Login Form

Inline login form

Log in

Example

Inline Search Form

Inline search form

Search

Example

Controlled syncing and event listeners (wired in one <script> block):

API

oas-form

Attribute	Description	Type	Default
gap	Spacing (grid gap in grid mode; item spacing in inline mode), token value e.g. var(--oas-space-4); 0 by default in grid, var(--oas-space-4) by default in inline	string	0
inline	Inline layout: items laid out horizontally (label on the left of the control, controls auto-width, wraps to new lines); item spacing follows gap (default var(--oas-space-4)); coexists with layout and takes precedence over it; forces label-align to left and label-width to auto	boolean	—
label-align	Label alignment: left / right / top (default top in grid mode; forced to left in inline mode)	string	top
label-width	Label column width when label-align is left/right (ignored in inline mode, auto)	—	—
layout	Layout mode: vertical (default, stacked) / grid (24-column grid); non-enum values fall back to vertical; inline attribute takes precedence when present	string	vertical
rules	Validation rules JSON: { 字段名: [{ required, message, minLength, maxLength, pattern }] }	Rules | string	{}

Event	Description
oas-submit	Validation passed, detail: { values }
oas-validate-fail	Validation failed, detail: { errors, values }

Name	Description
default	—

oas-form-item

Attribute	Description	Type	Default
label	Label text (no label row when omitted)	string	—
name	Field name (validation association)	—	—
required	Required asterisk (visual only; validation is still driven by form rules)	boolean	—
span	Columns spanned in the 24-column grid (only when form layout="grid"; non-integer in 1-24 → 24)	string	24

Name	Description
default	Field control

On validation failure, failed fields are marked aria-invalid; error messages can be retrieved via form.getErrors(). For fields wrapped in oas-form-item, the error text is collected into the form-item's error slot (role="alert").