Form

Overview

Form wraps a native <form> and consolidates validation across a registry of Fields. It surfaces the browser’s own ValidityState per field, gates when that validity is revealed (ValidationMode), and blocks submission and moves focus to the first invalid control when any field is invalid. Each Field cascades a shared discrete state (valid, invalid, dirty, touched, filled, focused, disabled) to its Label, Control and Error.

Anatomy

@using Navius.Primitives.Components.Form
@using Navius.Primitives.Components.Field

<NaviusForm>
    <NaviusField>
        <NaviusFieldLabel />
        <NaviusFieldControl />
        <NaviusFieldError />
        <NaviusFieldValidity />
    </NaviusField>

    <NaviusFormSubmit />
</NaviusForm>

Root

Wraps the whole form. Renders a native form element and manages the submit, validation and focus flow.

Prop	Type	Default	Description
OnSubmit	EventCallback	-	Invoked on native form submit when every field is valid.
Errors	IReadOnlyDictionary<string, string[]>?	-	Validation errors keyed by field name, surfaced by each field’s Error.
OnClearErrors	EventCallback	-	Fires before re-validating on submit and on reset, to clear stale errors.
PreventDefault	bool	true	When true, the native submit is prevented so the consumer owns submission.
ChildContent	RenderFragment?	-	The form’s fields and submit button.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered form.

Field

Groups a label, control and messages under one name. Renders a div.

Prop	Type	Default	Description
Name	string	"" (EditorRequired)	The field name.
Disabled	bool	false	Disables the field; takes precedence over the control’s own disabled.
Validity	FieldValidity?	-	Full validity snapshot driving messages and aria-invalid (controlled validity).
Invalid	bool	false	Convenience flag for marking the field invalid. Maps to CustomError.
ServerInvalid	bool	false	Server-side invalidity; auto-clears on the next user edit.
ValidationMode	FieldValidationMode	OnSubmit	When the field surfaces validity: OnSubmit, OnBlur, or OnChange.
ChildContent	RenderFragment?	-	The field’s label, control and messages.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

Label

The field’s label. Renders a native label whose for points at the control. Also carries a stable id a group-style Control (one without a native for target) can reference via aria-labelledby.

Prop	Type	Default	Description
ChildContent	RenderFragment?	-	Label content.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered label.

Control

The form control. With no ChildContent, renders a native input wired with the field id and aria-* by default. With ChildContent, cascades ControlProps (id, aria-describedby, aria-invalid) to a custom control instead, without the discrete state attributes below.

Prop	Type	Default	Description
ChildContent	RenderFragment<ControlProps>?	-	Optional custom control, receiving ControlProps (Id, DescribedBy, Invalid, and the discrete data-* state) to splat onto its own element.
Attributes	IDictionary<string, object>?	-	Forwarded to the default rendered input when ChildContent is omitted.

Error

A validation message tied to a match. Renders a div with role="alert" only while its match fails, and joins aria-describedby while shown.

Prop	Type	Default	Description
Match	string?	-	The validity key this message fires on (e.g. valueMissing, typeMismatch). Omit for a catch-all shown whenever the field is invalid.
ForceMatch	bool	false	Shows the message unconditionally regardless of validity.
ChildContent	RenderFragment?	-	Message content. When omitted, renders the field’s surfaced error strings (e.g. form errors by name).
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

Validity

Render-prop exposing the field’s live FieldValidity. Renders nothing itself.

Prop	Type	Default	Description
ChildContent	RenderFragment<FieldValidity>?	- (EditorRequired)	Receives the field’s current FieldValidity.

Submit

The form’s submit button. Renders a native button with type="submit".

Prop	Type	Default	Description
ChildContent	RenderFragment?	-	Button content.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered button.

Data attributes

Part	Attribute	Description
Root	data-navius-form	Present on the form element.
Field, Label, Control (default), Error	data-disabled	Present when the field is disabled.
Field, Label, Control (default), Error	data-valid	Present once validity has surfaced and the field is valid.
Field, Label, Control (default), Error	data-invalid	Present once validity has surfaced and the field is invalid, or the field is externally marked invalid.
Field, Label, Control (default), Error	data-dirty	Present once the control’s value differs from its initial value.
Field, Label, Control (default), Error	data-touched	Present once the control has been blurred at least once.
Field, Label, Control (default), Error	data-filled	Present while the control holds a non-empty value.
Field, Label, Control (default), Error	data-focused	Present while the control has focus.
Submit	data-navius-form-submit	Present on the submit button.

Keyboard interactions

Key	Behavior
Enter	Submits the form. When a field is invalid, submission is blocked and focus moves to the first invalid control.
Tab	Moves focus to the next control in the form.

ARIA mechanism

Built on the native form, label and form controls, so the browser’s own constraint-validation and accessibility semantics apply. The Label’s for points at the Control’s id; the Label also carries its own stable id so a group-style custom control (a ChildContent control rendering role="group" rather than a labelable native element) can point aria-labelledby at it instead. Active Error messages register their id into the Control’s aria-describedby. An invalid Control carries aria-invalid="true". A failed submit moves focus to the first invalid control. This mechanism is covered by the Playwright browser test suite and gated by axe-core in CI.