Form Model Reference

Overview

The Form Model is Webiny’s declarative form system for the admin UI. It provides a fluent builder API for defining fields, arranging them with a layout builder, validating with Zod schemas or imperative rules, and rendering with React. Fields support conditional visibility, computed values, and deeply nested object structures with dynamic zones.

The typical workflow is: define fields via form.fields(), arrange them with form.setLayout(), and render with the <FormView> component. For extending existing forms (e.g., page settings), use form.fields() and form.layout() to add new fields and layout nodes to an existing form model.

FormModel

field

Gets a single field instance by name. Supports dot-notation paths for nested object fields.

Signature:

form.field(name: string): IField

Parameters:

getField

Gets a field instance by name, returning undefined if the field does not exist.

Signature:

form.getField(name: string): IField | undefined

Parameters:

fields

Defines or adds fields to the form model. Can be called multiple times to extend an existing form.

Signature:

form.fields(factory: (fields: IFieldBuilderRegistry) => Record<string, IFieldBuilder | undefined>): void

Parameters:

removeField

Removes a field from the form model.

Signature:

form.removeField(name: string): void

Parameters:

layout

Modifies the existing layout by adding, removing, or repositioning layout nodes.

Signature:

form.layout(factory: (layout: ILayoutModifier) => (LayoutNode | IPositionedLayoutNode)[]): void

Parameters:

Overload — access a layout node by ID:

form.layout(nodeId: string): ILayoutNodeAccessHandle

setLayout

Sets the initial form layout. Use this when defining a form from scratch.

Signature:

form.setLayout(factory: (layout: ILayoutBuilder) => ILayoutNodeBuilder[]): void

Parameters:

getData

Returns all form data as a plain object.

Signature:

form.getData(): Record<string, unknown>

This method takes no parameters.

setData

Sets the form data, populating all field values.

Signature:

form.setData(data: Record<string, unknown>): void

Parameters:

validate

Validates all fields and form-level rules. Returns true if the form is valid.

Signature:

form.validate(): Promise<boolean>

This method takes no parameters.

submit

Validates the form and returns the form data if valid, or false if validation fails.

Signature:

form.submit<T = Record<string, unknown>>(): Promise<T | false>

This method takes no parameters.

addRule

Adds a cross-field validation rule. Accepts a Zod schema or an imperative validation function.

Signature:

form.addRule(rule: FormRule): void

Parameters:

reset

Resets the form to its initial state, clearing all dirty flags and validation results.

Signature:

form.reset(): void

This method takes no parameters.

focusField

Focuses a specific field, automatically activating any tabs needed to make it visible.

Signature:

form.focusField(name: string): void

Parameters:

Properties

Field Types

All fields are created via the fields registry callback passed to form.fields(). Each factory method returns a chainable field builder.

text

Creates a text field. Value: string | null. Default renderer: textInput.

Signature:

fields.text(): TextFieldBuilder

number

Creates a number field. Value: number | null. Default renderer: numberInput. Automatically normalizes string input to numbers.

Signature:

fields.number(): NumberFieldBuilder

boolean

Creates a boolean field. Value: boolean | null. Default renderer: switch.

Signature:

fields.boolean(): BooleanFieldBuilder

datetime

Creates a date/time field. Default renderer: dateTimeInput. Call a variant method to set the subtype:

Additional chainable methods:

Signature:

fields.datetime(): DateTimeFieldBuilder

file

Creates a file field. Value: FileValue | null (object with id, name, size, mimeType, src, width, height). Default renderer: filePicker.

Signature:

fields.file(): FileFieldBuilder

fileUrl

Creates a file URL field. Value: string | null (URL only). Default renderer: fileUrlPicker.

Signature:

fields.fileUrl(): FileUrlFieldBuilder

object

Creates an object field for nested structures, lists, and dynamic zones. Value: Record<string, unknown> | null. Default renderer: objectAccordionSingle.

Signature:

fields.object(): ObjectFieldBuilder

See Object Fields for the full object-specific API.

Field Builder Methods

These chainable methods are available on all field builders returned by the field type factories.

label

Sets the field label.

Signature:

builder.label(text: string): this

description

Sets the description text displayed below the field.

Signature:

builder.description(text: string): this

help

Sets the help text.

Signature:

builder.help(text: string): this

note

Sets a supplementary note.

Signature:

builder.note(text: string): this

placeholder

Sets the input placeholder text.

Signature:

builder.placeholder(text: string): this

defaultValue

Sets the default value. Can be a static value or a function for dynamic defaults.

Signature:

builder.defaultValue(value: unknown): this

required

Marks the field as required.

Signature:

builder.required(message?: string): this

Parameters:

requiredWhen

Conditionally marks the field as required based on other field values.

Signature:

builder.requiredWhen(fn: (form: IFormModel) => boolean, message?: string): this

Parameters:

schema

Sets a Zod validation schema for the field.

Signature:

builder.schema(zodSchema: z.ZodTypeAny): this

Parameters:

renderer

Overrides the default renderer for the field.

Signature:

builder.renderer(name: string, settings?: Record<string, unknown>): this

Parameters:

options

Adds value options. Automatically switches text/number fields to the dropdown renderer.

Signature:

builder.options(opts: IValueOption[] | ((form: IFormModel) => IValueOption[])): this

Parameters:

Each IValueOption has: { label: string, value: string | number, disabled?: boolean }.

list

Converts the field to an array field. Automatically switches renderers (e.g., textInput to textInputs, objectAccordionSingle to objectAccordionMultiple).

Signature:

builder.list(): this

hidden

Hides the field from the UI. The value remains in the form data.

Signature:

builder.hidden(): this

disabled

Disables the field.

Signature:

builder.disabled(value?: boolean): this

rules

Sets conditional visibility and disable rules for the field. See Conditional Rules.

Signature:

builder.rules(rules: IRule[]): this

computed

Makes the field always computed — its value is recalculated whenever dependencies change.

Signature:

builder.computed(fn: (form: IFormModel) => unknown): this

computedUntilDirty

Makes the field computed until the user manually edits it.

Signature:

builder.computedUntilDirty(fn: (form: IFormModel) => unknown): this

beforeChange

Adds a transform that runs before a value change is applied. Return the transformed value.

Signature:

builder.beforeChange(fn: (value: unknown, form: IFormModel) => unknown): this

afterChange

Adds a callback that runs after a value change is applied.

Signature:

builder.afterChange(fn: (value: unknown, form: IFormModel) => void): this

afterSetValue

Adds a callback that runs after a programmatic setValue() call.

Signature:

builder.afterSetValue(fn: (value: unknown, form: IFormModel) => void): this

onBlur

Adds a callback that runs when the field loses focus.

Signature:

builder.onBlur(fn: (value: unknown, form: IFormModel) => void): this

cloneValue

Sets custom clone logic for when a list item containing this field is duplicated.

Signature:

builder.cloneValue(fn: (value: unknown) => unknown): this

tags

Tags the field for programmatic lookup.

Signature:

builder.tags(tags: string[]): this

Field Instance

The IField interface represents a runtime field instance, returned by form.field("name").

getValue

Gets the current field value.

Signature:

field.getValue<T = unknown>(): T

setValue

Sets the field value, triggering beforeChange and afterChange callbacks.

Signature:

field.setValue(value: unknown): void

setValueSilent

Sets the field value without triggering callbacks.

Signature:

field.setValueSilent(value: unknown): void

as

Casts the field to a typed field interface.

Signature:

field.as<T extends keyof FieldTypeMap>(type: T): FieldTypeMap[T]

Parameters:

validate

Validates the field against its schema, required status, and rules.

Signature:

field.validate(options?: { force?: boolean }): Promise<boolean>

blur

Triggers the blur event on the field.

Signature:

field.blur(): void

focus

Requests focus on the field.

Signature:

field.focus(): void

remove

Removes the field from the form model.

Signature:

field.remove(): void

setDisabled

Sets the disabled state of the field.

Signature:

field.setDisabled(value: boolean): void

setVisible

Sets the visibility of the field.

Signature:

field.setVisible(value: boolean): void

Properties

Object Fields

Object fields support nested structures, lists, and dynamic zones (templates). Access via form.field("name").as("object") or use the ObjectFieldBuilder.

Builder Methods

fields

Defines child fields for the object.

Signature:

builder.fields(fn: (fields: IFieldBuilderRegistry) => Record<string, IFieldBuilder>): this

template

Defines a dynamic zone template. Calling .template() automatically switches the renderer to dynamicZone.

Signature:

builder.template(id: string, configure: (t: ITemplateBuilder) => void): this

The ITemplateBuilder supports:

listSchema

Adds a Zod validation schema for the list as a whole.

Signature:

builder.listSchema(schema: z.ZodTypeAny): this

Runtime Methods

These methods are available on IObjectField, accessed via form.field("name").as("object").

addItem

Adds a new item to a list object field. For templated fields, pass a template ID.

Signature:

objectField.addItem(templateIdOrData?: string | Record<string, unknown>, data?: Record<string, unknown>): void

removeItem

Removes an item from a list object field by index.

Signature:

objectField.removeItem(index: number): void

moveItem

Moves an item within a list object field.

Signature:

objectField.moveItem(fromIndex: number, toIndex: number): void

duplicateItem

Duplicates an item in a list object field.

Signature:

objectField.duplicateItem(index: number): void

setTemplate

Sets the active template on a single-value templated object field.

Signature:

objectField.setTemplate(templateId: string): void

Runtime Template Management

Templates can be added or removed at runtime via the templates property:

const sections = form.field("sections").as("object");

sections.templates.remove("text");

sections.templates.add("banner", t => {
    t.label("Banner").fields(f => ({
        headline: f.text().label("Headline").required()
    }));
});

Properties

Layout Builder

The layout builder controls how fields are arranged in the UI. Use form.setLayout() for initial layout definition, or form.layout() to modify an existing layout.

row

Arranges one or more fields in a horizontal row.

Signature:

layout.row(...fieldIds: string[]): IRowBuilder

separator

Adds a visual divider between layout sections.

Signature:

layout.separator(): ISeparatorBuilder

tabs

Creates a tabbed layout container.

Signature:

layout.tabs(id?: string): ITabsBuilder

The ITabsBuilder supports chaining:

The tab configure callback receives an ITabBuilder:

element

Adds a custom rendered element to the layout.

Signature:

layout.element(renderer: string, props?: Record<string, unknown>): IElementBuilder

object

Defines the inner layout for an object field.

Signature:

layout.object(fieldName: string, layout: (l: ILayoutBuilder) => ILayoutNodeBuilder[]): IObjectBuilder

Overload — per-template layouts for dynamic zones:

layout.object(fieldName: string, templateLayouts: Record<string, (l: ILayoutBuilder) => ILayoutNodeBuilder[]>): IObjectBuilder

Positioning

When modifying an existing layout, use .after() or .before() to position relative to existing fields:

layout.row("newField").after("existingField");
layout.row("anotherField").before("existingField");

The .replace(target) method removes the target and inserts the new node in its place.

Conditional Rules

Rules control field visibility and disabled state based on other field values. Pass them via the .rules() builder method.

Rule structure:

Operators

Built-in Renderers

Automatic Renderer Switching

• Calling .options() on text/number fields switches to dropdown
• Calling .list() on datetime switches to dateTimeInputs
• Calling .list() on object switches to objectAccordionMultiple
• Calling .template() on object switches to dynamicZone

Custom Renderers

createFieldRenderer

Creates a custom field renderer component.

Signature:

createFieldRenderer<TName extends string>(
    render: (props: { field: RendererField<TName> }) => React.ReactNode
): React.ComponentType<{ field: IFieldVM }>

createObjectFieldRenderer

Creates a custom renderer for object fields.

Signature:

createObjectFieldRenderer<TName extends string>(
    render: (props: { field: ObjectRendererField<TName> }) => React.ReactNode
): React.ComponentType<{ field: IFieldVM }>

FormView

The FormView component renders a form model in the UI.

Signature:

<FormView form={formModel.vm} renderers={fieldRenderers} layoutRenderers={layoutRenderers} />

Props: