Forms API

Full surface of @oge-ui/forms: the form itself, the two renderless configuration children, the standalone validation summary, and the application-wide configuration provider.

Properties Methods Events Types

OgeForm

oge-form

Properties 27

Binding

Name	Type	Default	Description
`fieldTree`	`FieldTree<T> \| undefined`	`undefined`	An Angular Signal Forms tree, as returned by `form()`. The caller owns validation, required marks, disabled and readonly state.
`formGroup`	`FormGroup \| undefined`	`undefined`	A reactive `FormGroup`. Each item binds its matching control through the editors' control-value-accessor path.
`formData`	`T \| undefined`	`undefined`	A plain model object — two-way. The form builds its own Signal Forms tree over it, compiling each item's `validationRules` into the schema.
`items`	`readonly OgeFormItemData[] \| undefined`	`undefined`	Data-driven items, rendered after the projected `<oge-form-item>` children.
`groups`	`readonly OgeFormGroupData[] \| undefined`	`undefined`	Data-driven groups, matched to items by `key` (or `caption`) through an item's `group`.
`mode`	`Signal<OgeFormMode>`	—	Read-only: which binding the form resolved to. Derived from the bound inputs, never configured.

Layout

Name	Type	Default	Description
`colCount`	`number \| 'auto'`	`'auto'`	Layout columns. `'auto'` fits as many `minColWidth` tracks as the form is wide.
`colCountByScreen`	`Partial<Record<OgeFormScreenSize, number>> \| undefined`	`undefined`	Column count per breakpoint. Implemented as container queries on the form itself, so a form in a dialog or a grid cell sizes from its own width — not the window's.
`minColWidth`	`number`	`220`	Narrowest column `colCount: 'auto'` will produce, in pixels.
`labelLocation`	`'top' \| 'start' \| 'end'`	`'top'`	`'top'` keeps each editor's own label chrome; the side values hand the label to the form, which draws a real `<label for>` in its own column.
`labelMode`	`'static' \| 'floating' \| 'hidden' \| 'outside'`	`'static'`	Forwarded to every editor. Forced to `'hidden'` when `labelLocation` is a side value, so no label renders twice.
`alignItemLabels`	`boolean`	`true`	Gives side labels one shared column width so the editors line up.
`showColonAfterLabel`	`boolean`	`false`	Appends `messages.labelColon` to every label.
`showRequiredMark`	`boolean`	`true`	Renders `messages.requiredMark` after a required label, `aria-hidden`, with a screen-reader-only word beside it.
`showOptionalMark`	`boolean`	`false`	Renders `messages.optionalMark` after every non-required label.
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Forwarded to every editor.
`stylingMode`	`'outlined' \| 'filled' \| 'underlined'`	`'outlined'`	Forwarded to every editor.
`subscriptSizing`	`'fixed' \| 'dynamic' \| 'none'`	`'fixed'`	Forwarded to every editor. `'fixed'` reserves the hint/error line so an appearing error never shifts the layout.

State

Name	Type	Default	Description
`readOnly`	`boolean`	`false`	Makes every editor read-only, overridable per group and per item. In `[fieldTree]` mode use the schema's `readonly()` instead.
`disabled`	`boolean`	`false`	Wraps the fields in a `<fieldset disabled>`. In `[fieldTree]` mode use the schema's `disabled()` — the `FormField` directive writes the editor's `disabled` input itself.
`showValidationSummary`	`boolean`	`false`	Renders an `<oge-validation-summary>` above the fields once a submit has failed.
`scrollToFirstInvalid`	`boolean`	`true`	Scrolls the first invalid field into view when a submit fails. Focus moves there either way.
`errors`	`Signal<readonly OgeFormErrorEntry[]>`	—	Read-only: one entry per invalid field, in layout order, regardless of whether the field is showing its error yet.
`valid`	`Signal<boolean>`	—	Read-only: whether every bound field currently validates.
`dirty`	`Signal<boolean>`	—	Read-only: whether any bound field has been edited since the last reset. Works in all three binding modes.
`messages`	`Partial<OgeFormsMessages> \| undefined`	`undefined`	Per-instance string overrides, merged over `provideOgeFormsConfig()`.
`renderFormElement`	`boolean`	`true`	Whether the fields are wrapped in a real `<form>`. Set `false` inside another form — nested forms are invalid HTML; the grid's row editor does exactly this. With `false` there is no native submit, so drive it with `submit()`.

Methods 8

Name	Type	Description
`submit(event?: Event)`	`Promise<boolean>`	Marks every field touched, validates, emits `submitting` and then `submitted`. Resolves `false` when the form was invalid or the submit was canceled, and focuses the first invalid field.
`validate()`	`boolean`	Re-reads validity and emits `validated`. Does not move focus.
`reset(values?: Partial<T>)`	`void`	Resets every field to `values`, or to the bound form's initial data, and hides the validation summary.
`clear()`	`void`	Empties every editor using the per-`dataType` empty value (`''`, `null`, `false`, `[]`).
`focus(field?: string)`	`void`	Focuses a named field, or the first one when called with no argument.
`focusFirstInvalid()`	`boolean`	Focuses — and, with `scrollToFirstInvalid`, scrolls to — the first invalid field. Returns `false` when the form is valid.
`itemOption(field: string)`	`OgeResolvedFormItem \| undefined`	The resolved configuration of one item, as the form actually renders it. Replaces the reference libraries' `getEditor()`, which hands out a component instance.
`updateData(field: string, value: unknown)`	`void`	Writes one field. The overload `updateData(partial)` merges an object into the bound data.

Events 5

Name	Type	Description
`submitting`	`OgeFormSubmittingEvent<T>`	Cancelable pre-submit — `{ data, valid, cancel, event }`. Set `cancel` to stop the submit.
`submitted`	`OgeFormSubmittedEvent<T>`	Emitted after a submit passed validation and was not canceled.
`fieldChanged`	`OgeFormFieldChangedEvent`	One field's value changed — `{ field, value, previousValue }`.
`validated`	`OgeFormValidatedEvent`	Emitted after `validate()` or a submit attempt — `{ valid, errors }`.
`editorEnterKey`	`OgeFormKeyEvent`	Enter pressed inside an editor — `{ field, event }`.

Types 10

Name	Type	Description
`OgeFormMode`	`'fieldTree' \| 'formGroup' \| 'formData'`	Which binding the form resolved to.
`OgeFormDataType`	`'string' \| 'number' \| 'boolean' \| 'date' \| 'datetime' \| 'dateRange' \| 'array' \| 'object'`	Value shape of an item. Inferred from the model value when not set.
`OgeFormEditorType`	`'textBox' \| 'textArea' \| 'numberBox' \| 'selectBox' \| 'tagBox' \| 'autocomplete' \| 'treeSelect' \| 'dateBox' \| 'dateRangeBox' \| 'calendar' \| 'checkBox' \| 'switch' \| 'radioGroup'`	Which `@oge-ui/inputs` editor renders an item. House camelCase names, not the reference libraries' class names.
`OgeFormLabelLocation`	`'top' \| 'start' \| 'end'`	Where an item's label sits relative to its editor.
`OgeFormScreenSize`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	Container-query breakpoints: under 480, then 480 / 720 / 960 / 1200 pixels of form width.
`OgeFormColCount`	`number \| 'auto'`	A fixed track count, or auto-fit by `minColWidth`.
`OgeValidationRule`	`{ type: 'required' \| 'email' \| 'numeric' \| 'stringLength' \| 'pattern' \| 'range' \| 'custom' \| 'async'; … }`	A declarative rule. Compiled into an Angular Signal Forms schema — there is no second validation engine.
`OgeValidationContext`	`{ value: unknown; data: Record<string, unknown> }`	What a `custom` rule sees: its own value and the whole model, which is what makes cross-field rules possible.
`OgeFormErrorEntry`	`{ field: string; label: string; message: string }`	One row of the validation summary.
`OgeResolvedFormItem`	`interface`	An item after label defaulting, dataType inference, editor selection and state inheritance — what `itemOption()` returns.

OgeFormItem

oge-form-item

Properties 17

Name	Type	Default	Description
`field`	`string`	—	Required. Model property this item edits; dot-notation reaches nested objects.
`key`	`string \| undefined`	`undefined`	Stable identity; defaults to `field`.
`label`	`string \| undefined`	`undefined`	Label text. Defaults to a title-cased `field` — `postalCode` becomes “Postal code”.
`labelVisible`	`boolean`	`true`	Set `false` to render the editor with no label.
`hint`	`string \| undefined`	`undefined`	Help text under the editor. Chrome editors render it in their own subscript; bare controls get it from the form.
`placeholder`	`string \| undefined`	`undefined`	Placeholder forwarded to the editor.
`dataType`	`OgeFormDataType \| undefined`	`undefined`	Value shape. Inferred from the current model value when omitted.
`editorType`	`OgeFormEditorType \| undefined`	`undefined`	Explicit editor; beats both `editorOptions.items` and `dataType`.
`editorOptions`	`OgeFormEditorOptions \| undefined`	`undefined`	A curated, typed subset of editor inputs (`items`, `displayExpr`, `min`, `max`, `rows`, …). Supplying `items` selects a select box or tag box.
`colSpan`	`number`	`1`	Layout columns the item spans, clamped to the column count in force.
`visible`	`boolean`	`true`	A hidden item is dropped from the layout entirely — no hidden input, no stale DOM value.
`visibleIndex`	`number \| undefined`	`undefined`	Items with an index come first, in index order; everything else keeps its declaration order behind them.
`isRequired`	`boolean`	`false`	Adds a `required` rule and shows the required mark.
`validationRules`	`readonly OgeValidationRule[] \| undefined`	`undefined`	Declarative rules, compiled into the form's Signal Forms schema. Ignored — with a dev-mode warning — when the form is bound with `[fieldTree]` or `[formGroup]`.
`readOnly`	`boolean \| undefined`	`undefined`	`undefined` falls back to the enclosing group, then the form.
`disabled`	`boolean \| undefined`	`undefined`	`undefined` falls back to the enclosing group, then the form.
`cssClass`	`string \| undefined`	`undefined`	Extra class on the item wrapper.

OgeFormGroup

oge-form-group

Properties 9

Name	Type	Default	Description
`caption`	`string`	`''`	Legend text. An empty caption renders an unlabelled section.
`key`	`string \| undefined`	`undefined`	Stable identity; defaults to the caption.
`colCount`	`OgeFormColCount \| undefined`	`undefined`	Columns inside this group; `undefined` inherits the form's count.
`colSpan`	`number`	`1`	Columns the group itself spans in its parent layout.
`visible`	`boolean`	`true`	Drops the whole section, and its items, from the layout.
`disabled`	`boolean \| undefined`	`undefined`	Disables every item in the section, unless the item overrides it.
`readOnly`	`boolean \| undefined`	`undefined`	Makes every item in the section read-only, unless the item overrides it.
`visibleIndex`	`number \| undefined`	`undefined`	Explicit ordering among this group's siblings. Ordering is scoped per level, the way the reference libraries scope it.
`cssClass`	`string \| undefined`	`undefined`	Extra class on the fieldset.

OgeValidationSummary

oge-validation-summary

Properties 2

Name	Type	Default	Description
`errors`	`readonly OgeFormErrorEntry[]`	`[]`	One entry per invalid field, in layout order. Bind `form.errors()`.
`messages`	`Partial<OgeFormsMessages> \| undefined`	`undefined`	Per-instance string overrides.

Events 1

Name	Type	Description
`errorClick`	`OgeFormErrorEntry`	A summary row was activated. Bind it to `form.focus($event.field)`.

Sections

Properties 18

OgeFormTabs — <oge-form-tabs>

Name	Type	Default	Description
`selectedIndex`	`number`	`0`	Open tab — two-way. A failed submit sets it to the tab holding the first invalid field.
`deferRendering`	`boolean`	`false`	Deliberately the opposite of the tab panel's own default: a form usually wants every field in the DOM. Validation runs on the model either way.
`keepAlive`	`boolean`	`true`	Keeps a rendered tab's fields mounted while it is hidden.
`showErrorBadges`	`boolean`	`true`	Shows each tab's invalid-field count as a badge on the tab.
`key / visible / visibleIndex / colSpan / cssClass`	`string \| boolean \| number \| undefined`	—	The same section-level knobs a group has.

OgeFormSteps — <oge-form-steps>

Name	Type	Default	Description
`activeIndex`	`number`	`0`	Active step — two-way. A failed submit moves to the step holding the first invalid field.
`linear`	`boolean`	`false`	Blocks moving past a step that still has invalid fields. Completion comes from the form's own per-step error rollup, so it behaves identically in all three binding modes.
`orientation`	`'horizontal' \| 'vertical'`	`'horizontal'`	Passed through to the stepper.
`showNavigation`	`boolean`	`true`	Renders the stepper's built-in Back / Next bar. On by default here, because a wizard inside a form almost always wants one.
`touchOnLeave`	`boolean`	`true`	Touches only the leaving step's fields on each advance, so the steps ahead stay quiet instead of turning red — which a plain `markAllAsTouched()` would cause.
`showInvalidSections`	`boolean`	`true`	Flags a step whose fields are invalid, driving the stepper's error indicator.
`deferRendering / keepAlive`	`boolean`	—	See `OgeFormTabs` — same defaults, same reasoning.
`key / visible / visibleIndex / colSpan / cssClass`	`string \| boolean \| number \| undefined`	—	The same section-level knobs a group has.

OgeFormAccordion — <oge-form-accordion>

Name	Type	Default	Description
`expandedKeys`	`readonly string[]`	`[]`	Expanded panels — two-way. A failed submit adds the panel holding the first invalid field.
`multiple`	`boolean`	`true`	Whether more than one panel may be open at a time.
`collapsible`	`boolean`	`true`	Whether the open panel may be closed again.
`showInvalidSections`	`boolean`	`true`	Drives the accordion's own invalid indicator — danger rail, dot and screen-reader label — from the panel's field errors.
`deferRendering / keepAlive`	`boolean`	—	As on `<oge-form-tabs>`.

Template slots

Properties 5

Slots

Name	Type	Description
`ogeFormItemTemplate`	`directive — [ogeFormItemTemplate]`	Replaces a field entirely: label, editor and error text. Legal at form level (every item) or inside one `<oge-form-item>`, where it wins.
`ogeFormEditorTemplate`	`directive — [ogeFormEditorTemplate]`	Replaces only the control, keeping the form's label, required mark and error chrome. The escape hatch for anything `editorOptions` cannot express.
`ogeFormLabelTemplate`	`directive — [ogeFormLabelTemplate]`	Replaces the label content. The surrounding `<label for>` stays, so the control association and the required mark survive.
`ogeFormGroupCaptionTemplate`	`directive — [ogeFormGroupCaptionTemplate]`	Replaces the content of a group's `<legend>`. The fieldset/legend pair itself stays — that is what makes the section a labelled group.
`ogeFormActions`	`directive — [ogeFormActions]`	Marks the projected action bar (submit, reset, …). A typed marker rather than a bare attribute.

Types 3

Name	Type	Description
`OgeFormItemTemplateContext`	`{ $implicit: OgeResolvedFormItem; item; field; control; error; editorId }`	Context of the item and editor slots. `field` is the Signal Forms node (bind with `[formField]`), `control` the reactive one, and `editorId` the id the form's `<label for>` points at.
`OgeFormLabelTemplateContext`	`{ $implicit: string; item; required; editorId }`	Context of the label slot; `$implicit` is the resolved label text.
`OgeFormGroupCaptionTemplateContext`	`{ $implicit: string }`	Context of the group caption slot.

Schema metadata

Properties 10

Schema-carried layout

Name	Type	Description
`OGE_FORM_LABEL`	`MetadataKey<string>`	Label text, set with `metadata(path, OGE_FORM_LABEL, () => '…')` in a Signal Forms schema.
`OGE_FORM_HINT`	`MetadataKey<string>`	Help text under the editor.
`OGE_FORM_PLACEHOLDER`	`MetadataKey<string>`	Editor placeholder.
`OGE_FORM_COL_SPAN`	`MetadataKey<number>`	Layout columns the field spans.
`OGE_FORM_EDITOR`	`MetadataKey<OgeFormEditorType>`	Explicit editor for the field.
`OGE_FORM_EDITOR_OPTIONS`	`MetadataKey<OgeFormEditorOptions>`	Curated editor inputs.
`OGE_FORM_DATA_TYPE`	`MetadataKey<OgeFormDataType>`	Value shape, when the live value is not descriptive enough.
`OGE_FORM_GROUP`	`MetadataKey<string>`	Caption of the group the field belongs to; the group is created on demand.
`OGE_FORM_ORDER`	`MetadataKey<number>`	Ordering hint, equivalent to an item's `visibleIndex`.
`itemFromMetadata(field, node)`	`OgeFormItemData \| undefined`	Builds one item description from a field's metadata; `undefined` for a field the schema hid with `hidden()`.

Forms configuration

Properties 18

provideOgeFormsConfig()

Name	Type	Default	Description
`labelLocation`	`OgeFormLabelLocation \| undefined`	`'top'`	Application-wide default for the input of the same name.
`minColWidth`	`number \| undefined`	`220`	Application-wide default for the input of the same name.
`showRequiredMark`	`boolean \| undefined`	`true`	Application-wide default for the input of the same name.
`showOptionalMark`	`boolean \| undefined`	`false`	Application-wide default for the input of the same name.
`showColonAfterLabel`	`boolean \| undefined`	`false`	Application-wide default for the input of the same name.

OgeFormsMessages

Name	Type	Default	Description
`requiredMark`	`string`	`'*'`	Marker after a required label; rendered aria-hidden.
`optionalMark`	`string`	`'optional'`	Marker after an optional label.
`requiredLabel`	`string`	`'required'`	Screen-reader text beside the required mark.
`optionalLabel`	`string`	`'optional'`	Screen-reader text beside the optional mark.
`labelColon`	`string`	`':'`	Separator drawn when `showColonAfterLabel`.
`validationSummaryTitle`	`string`	`'{count} fields need your attention'`	Summary heading; `{count}` is interpolated.
`validationSummaryTitleOne`	`string`	`'1 field needs your attention'`	Summary heading when exactly one field is invalid.
`validationSummaryLabel`	`string`	`'Validation summary'`	Accessible label of the summary region.
`invalidError`	`string`	`'This value is invalid'`	Fallback text for an error with no resolvable message.
`submitButton`	`string`	`'Submit'`	Label of the built-in submit button.
`resetButton`	`string`	`'Reset'`	Label of the built-in reset button.
`submitting`	`string`	`'Submitting…'`	Announced while an async submit handler is in flight.
`noItems`	`string`	`'No fields to display'`	Shown when no visible item resolves.