Form

An interactive form block with configurable fields that submits data to an endpoint

The Form block supports two configuration formats: a fields array (used by the visual builder) and a JSON Schema (for advanced use cases). Both are fully supported at runtime.

Basic Example (Fields Array)

The fields array is the primary format produced by the WYSIWYG Builder’s visual form designer.

{
  "type": "form",
  "action_url": "https://api.example.com/submit",
  "submit_text": "Submit",
  "fields": [
    {
      "id": "name",
      "field_type": "text",
      "label": "Name",
      "placeholder": "Enter your name",
      "required": true
    }
  ]
}

Complete Example (Fields Array)

Example Code

[
  {
    "type": "form",
    "action_url": "https://api.example.com/submit-ticket",
    "method": "POST",
    "submit_text": "Submit Ticket",
    "cancel_text": "Cancel",
    "block_id": "support_ticket_form",
    "layout": "stacked",
    "fields": [
      {
        "id": "name",
        "field_type": "text",
        "label": "Full Name",
        "placeholder": "Enter your name",
        "required": true,
        "min_length": 2,
        "max_length": 100
      },
      {
        "id": "email",
        "field_type": "email",
        "label": "Email Address",
        "placeholder": "[e-mail]",
        "required": true
      },
      {
        "id": "priority",
        "field_type": "select",
        "label": "Priority",
        "required": true,
        "options": [
          { "label": "Low", "value": "low" },
          { "label": "Medium", "value": "medium" },
          { "label": "High", "value": "high" },
          { "label": "Critical", "value": "critical" }
        ]
      },
      {
        "id": "description",
        "field_type": "textarea",
        "label": "Description",
        "placeholder": "Describe your issue...",
        "required": true
      },
      {
        "id": "agree_to_terms",
        "field_type": "checkbox",
        "label": "I agree to the terms and conditions",
        "required": true
      }
    ]
  }
]

JSON Schema Format (Advanced)

For advanced use cases, you can provide a standard JSON Schema instead of a fields array. The form renderer will use SchemaAutoForm to auto-generate the UI.

{
  "type": "form",
  "action_url": "https://api.example.com/submit",
  "schema": {
    "type": "object",
    "properties": {
      "name": { "type": "string", "title": "Name" },
      "priority": { "type": "string", "title": "Priority", "enum": ["Low", "Medium", "High"] },
      "notes": { "type": "string", "title": "Notes", "uniforms": { "multiline": true } }
    },
    "required": ["name", "priority"]
  }
}

Properties

type · string · required

Identifies this as a form block

Must be form

action_url · string · required

The endpoint URL to POST form data to when submitted

method · string · default: "POST" · required

The HTTP method for the form submission

Allowed values: POST, PUT, PATCH

submit_text · string · default: "Submit" · required

The label text for the submit button

cancel_text · string · required

The label text for an optional cancel button. Leave empty to hide the cancel button.

block_id · string · required

A unique identifier for this form block. Included in the submission payload.

layout · string · default: "stacked" · required

Controls how form fields are arranged

Allowed values: stacked (vertical), columns (side-by-side), inline (horizontal)

fields · array · required

An array of field objects that define the form fields. This is the format produced by the visual builder. Each field has properties like id, field_type, label, placeholder, required, options, etc. See Field Types below.

schema · object · required

A JSON Schema object that defines the form fields. Alternative to fields for advanced use cases. See JSON Schema Field Types below.

model · object · required

Default values for the form fields. Keys should match field IDs (for fields array) or property names (for schema).

{
  "name": "John Doe",
  "priority": "Medium"
}

Field Types (Fields Array)

When using the fields array format, each field object supports the following field_type values:

Field Type	Rendered As	Notes
text	Text input	Single-line text, supports min_length, max_length, pattern
textarea	Textarea	Multi-line text input
number	Number input	Numeric input, supports min, max
email	Email input	Validates email format
url	URL input	Validates URL format
password	Password input	Masked text input
date	Date picker	Calendar selector
select	Select dropdown	Requires options array with { label, value } pairs
radio	Radio buttons	Requires options array with { label, value } pairs
checkbox	Checkbox	Boolean toggle

Field Properties

Property	Type	Description
id	string	Unique field identifier (used as key in submission payload)
field_type	string	One of the field types above
label	string	Display label for the field
placeholder	string	Placeholder text
required	boolean	Whether the field is required
default_value	any	Default value
help_text	string	Helper text shown below the field
min_length	number	Minimum string length (text/textarea/password)
max_length	number	Maximum string length (text/textarea/password)
min	number	Minimum value (number)
max	number	Maximum value (number)
pattern	string	Regex pattern for validation (text)
options	array	Options for select/radio: [{ "label": "...", "value": "..." }]

Field Types (JSON Schema)

When using the schema format, field types are determined by the JSON Schema type and format:

JSON Schema Type	Rendered As	Notes
string	Text input	Default for string types
string + format: "email"	Email input	Validates email format
string + format: "uri"	URL input	Validates URL format
string + format: "date"	Date picker	Calendar selector
string + uniforms.multiline: true	Textarea	Multi-line text input
string + enum: [...]	Select dropdown	Options from enum values
number / integer	Number input	Numeric input with validation
boolean	Checkbox	Toggle on/off

Submission Payload

When the form is submitted, the following payload is POSTed to the action_url:

{
  "type": "form_submit",
  "block_id": "support_ticket_form",
  "values": {
    "name": "Jason",
    "email": "[e-mail]",
    "priority": "high",
    "description": "Need help with integration",
    "agree_to_terms": true
  }
}

Server Response

The server can respond with the same action types as Button responses:

{
  "action": "replace",
  "blocks": [
    {
      "type": "alert",
      "severity": "success",
      "text": "Ticket #1234 created successfully!"
    }
  ]
}

Nesting Rules

The form block can be placed inside:

• Root level
• Section
• Wizard Step
• Column Layout columns

Usage Notes

• The WYSIWYG Builder uses the fields array format with its visual form designer — no JSON editing required
• When using fields, a JSON Schema is generated internally for rendering via SchemaAutoForm
• Both fields and schema formats produce identical rendered forms
• Forms support client-side validation before submission
• Server-side validation errors can be returned and displayed inline