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:

Parameters:

getField

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

Signature:

Parameters:

fields

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

Signature:

Parameters:

removeField

Removes a field from the form model.

Signature:

Parameters:

layout

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

Signature:

Parameters:

Overload — access a layout node by ID:

setLayout

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

Signature:

Parameters:

getData

Returns all form data as a plain object.

Signature:

This method takes no parameters.

setData

Sets the form data, populating all field values.

Signature:

Parameters:

validate

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

Signature:

This method takes no parameters.

submit

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

Signature:

This method takes no parameters.

addRule

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

Signature:

Parameters:

reset

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

Signature:

This method takes no parameters.

focusField

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

Signature:

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:

number

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

Signature:

boolean

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

Signature:

datetime

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

Additional chainable methods:

Signature:

file

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

Signature:

fileUrl

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

Signature:

object

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

Signature:

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:

description

Sets the description text displayed below the field.

Signature:

help

Sets the help text.

Signature:

note

Sets a supplementary note.

Signature:

placeholder

Sets the input placeholder text.

Signature:

defaultValue

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

Signature:

required

Marks the field as required.

Signature:

Parameters:

requiredWhen

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

Signature:

Parameters:

schema

Sets a Zod validation schema for the field.

Signature:

Parameters:

renderer

Overrides the default renderer for the field.

Signature:

Parameters:

options

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

Signature:

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:

hidden

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

Signature:

disabled

Disables the field.

Signature:

rules

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

Signature:

computed

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

Signature:

computedUntilDirty

Makes the field computed until the user manually edits it.

Signature:

beforeChange

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

Signature:

afterChange

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

Signature:

afterSetValue

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

Signature:

onBlur

Adds a callback that runs when the field loses focus.

Signature:

cloneValue

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

Signature:

tags

Tags the field for programmatic lookup.

Signature:

Field Instance

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

getValue

Gets the current field value.

Signature:

setValue

Sets the field value, triggering beforeChange and afterChange callbacks.

Signature:

setValueSilent

Sets the field value without triggering callbacks.

Signature:

as

Casts the field to a typed field interface.

Signature:

Parameters:

validate

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

Signature:

blur

Triggers the blur event on the field.

Signature:

focus

Requests focus on the field.

Signature:

remove

Removes the field from the form model.

Signature:

setDisabled

Sets the disabled state of the field.

Signature:

setVisible

Sets the visibility of the field.

Signature:

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:

template

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

Signature:

The ITemplateBuilder supports:

listSchema

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

Signature:

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:

removeItem

Removes an item from a list object field by index.

Signature:

moveItem

Moves an item within a list object field.

Signature:

duplicateItem

Duplicates an item in a list object field.

Signature:

setTemplate

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

Signature:

Runtime Template Management

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

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:

separator

Adds a visual divider between layout sections.

Signature:

tabs

Creates a tabbed layout container.

Signature:

The ITabsBuilder supports chaining:

The tab configure callback receives an ITabBuilder:

element

Adds a custom rendered element to the layout.

Signature:

object

Defines the inner layout for an object field.

Signature:

Overload — per-template layouts for dynamic zones:

Positioning

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

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:

createObjectFieldRenderer

Creates a custom renderer for object fields.

Signature:

FormView

The FormView component renders a form model in the UI.

Signature:

Props: