Form Builder - Element Types Documentation

Text Input

Single line text input with pattern validation and length constraints.

Hidden Fields: Set hidden: true to hide the field from display while including its value in form data. Hidden fields use their default value and are not rendered in the form.

Schema Definition

Live Preview

Read Only

Available Properties

type: "text" (required)
key: Field identifier (required)
label: Display label for the field
placeholder: Placeholder text
required: Whether field is required (boolean)
minLength: Minimum character length (number)
maxLength: Maximum character length (number)
pattern: Regular expression for validation
default: Default value
description: Field description (shows in tooltip)
hint: Additional hint text (shows in tooltip)
actions: Array of action buttons for readonly mode
hidden: Hide field from form display but include in data (boolean)

Textarea

Multi-line text input with configurable row height.

Schema Definition

Live Preview

Read Only

Available Properties

type: "textarea" (required)
key: Field identifier (required)
label: Display label for the field
placeholder: Placeholder text
rows: Number of visible rows (default: 4)
required: Whether field is required (boolean)
minLength: Minimum character length (number)
maxLength: Maximum character length (number)
default: Default value
description: Field description (shows in tooltip)
hint: Additional hint text (shows in tooltip)
actions: Array of action buttons for readonly mode
hidden: Hide field from form display but include in data (boolean)

Number Input

Numeric input with min/max/step validation.

Schema Definition

Live Preview

Read Only

Available Properties

type: "number" (required)
key: Field identifier (required)
label: Display label for the field
placeholder: Placeholder text
required: Whether field is required (boolean)
min: Minimum value (number)
max: Maximum value (number)
step: Step increment for input controls
default: Default value
description: Field description (shows in tooltip)
hint: Additional hint text (shows in tooltip)
actions: Array of action buttons for readonly mode
hidden: Hide field from form display but include in data (boolean)

Select Dropdown

Dropdown selection with predefined options.

Schema Definition

Live Preview

Read Only

Available Properties

type: "select" (required)
key: Field identifier (required)
label: Display label for the field
required: Whether field is required (boolean)
options: Array of {value, label} option objects (required)
default: Default selected value (must match an option value)
description: Field description (shows in tooltip)
hint: Additional hint text (shows in tooltip)
actions: Array of action buttons for readonly mode
hidden: Hide field from form display but include in data (boolean)

File Upload

File upload with preview, drag-and-drop, and file type restrictions. Supports both single and multiple files.

Multiple Files: Set multiple: true to allow multiple file selection. Use min and max properties to control file count limits.

Schema Definition

Live Preview

Read Only

Available Properties

type: "file" (required)
key: Field identifier (required)
label: Display label for the field
required: Whether field is required (boolean)
accept: Object with file restrictions
accept.extensions: Array of allowed file extensions
accept.maxSize: Maximum file size in bytes
multiple: Allow multiple file selection (boolean)
minCount: Minimum number of files (when multiple is true)
maxCount: Maximum number of files (when multiple is true)
default: Default file resource ID or array for multiple
description: Field description (shows in tooltip)
hint: Additional hint text (shows in tooltip)
actions: Array of action buttons for readonly mode
hidden: Hide field from form display but include in data (boolean)

Multiple Files (Legacy)

Multiple file uploads with grid preview, count limits, and drag-and-drop.

⚠️ Deprecated: The files type is deprecated. Use file with multiple: true instead for consistent API design.

Schema Definition

Live Preview

Read Only

Available Properties

type: "files" (required)
key: Field identifier (required)
label: Display label for the field
required: Whether field is required (boolean)
min: Minimum number of files (number)
max: Maximum number of files (number)
accept: Object with file restrictions
accept.extensions: Array of allowed file extensions
accept.maxSize: Maximum file size in bytes
default: Array of default file resource IDs
description: Field description (shows in tooltip)
hint: Additional hint text (shows in tooltip)
actions: Array of action buttons for readonly mode
hidden: Hide field from form display but include in data (boolean)

Conditional Visibility (displayIf)

Control field visibility dynamically based on the value of another field. The displayIf property allows you to show or hide fields conditionally.

How it works: Add a displayIf object with key (the field to watch) and equals (the value that triggers visibility). The field will only render when the condition is met.

Example: Background Mode Selector

This example demonstrates a select field that controls which additional fields appear. When you select "Upload Image", a file upload field appears. Select "Solid Color" to show a text field for hex color codes. Choose "AI Generate" to display a textarea for generation prompts. Select "None" to hide all conditional fields.

{
  "type": "select",
  "key": "background_mode",
  "label": "Background Mode",
  "options": [
    {"value": "", "label": "Select mode..."},
    {"value": "none", "label": "None"},
    {"value": "image", "label": "Upload Image"},
    {"value": "colour", "label": "Solid Color"},
    {"value": "generate", "label": "AI Generate"}
  ],
  "required": true
},
{
  "type": "file",
  "key": "background_image",
  "label": "Background Image",
  "displayIf": {
    "key": "background_mode",
    "equals": "image"
  }
},
{
  "type": "text",
  "key": "background_color",
  "label": "Background Color (Hex Code)",
  "pattern": "^[0-9A-Fa-f]{6}$",
  "displayIf": {
    "key": "background_mode",
    "equals": "colour"
  }
},
{
  "type": "textarea",
  "key": "generation_prompt",
  "label": "AI Generation Description",
  "rows": 4,
  "displayIf": {
    "key": "background_mode",
    "equals": "generate"
  }
}

displayIf Properties

key: The field key to watch for changes (required)
equals: The exact value that makes this field visible (required)

Supported Field Types

The displayIf property can be used with any field type:

Text inputs
Textarea fields
Number inputs
Select dropdowns
File uploads
Containers (nested fields)

Nested Path Support

You can reference fields in nested containers using dot notation:

{
  "type": "text",
  "key": "city_specific_field",
  "displayIf": {
    "key": "address.city",
    "equals": "New York"
  }
}

Or reference fields in repeatable containers using array indices:

{
  "type": "text",
  "key": "follow_up_question",
  "displayIf": {
    "key": "answers[0].rating",
    "equals": "poor"
  }
}

Usage Notes

Validation: Hidden conditional fields are not validated. Only visible fields are included in form validation.
Data: Hidden fields do not appear in form data output. Their values are cleared when they become hidden.
Performance: Visibility is evaluated in real-time as field values change. No manual refresh needed.
Required Fields: Conditional fields can be marked as required: true, but validation only applies when visible.

Try It Out

Demo: Load the "Conditional Fields (displayIf)" example from the main demo page to see this feature in action. Change the Background Mode dropdown to see different fields appear and disappear dynamically.

Container

Nested object container with support for both single objects and repeatable arrays.

Multiple Containers: Set multiple: true to create repeatable container arrays. Use minCount and maxCount to control item limits.

Schema Definition

Live Preview

Read Only

Available Properties

type: "container" (required)
key: Field identifier (required)
label: Display label for the container
elements: Array of nested form elements (required)
multiple: Make container repeatable (boolean)
minCount: Minimum number of container instances (when multiple is true)
maxCount: Maximum number of container instances (when multiple is true)
description: Container description (shows in tooltip)
hint: Additional hint text (shows in tooltip)
actions: Array of action buttons for readonly mode
hidden: Hide field from form display but include in data (boolean)

Group Container (Legacy)

Nested object container with optional repeatable arrays (min/max items).

⚠️ Deprecated: The group type is deprecated. Use container with multiple: true instead. Groups use repeat: {min, max} syntax which is being replaced by minCount and maxCount properties.

Schema Definition

Live Preview

Read Only

Available Properties

type: "group" (required)
key: Field identifier (required)
label: Display label for the group
elements: Array of nested form elements (required)
repeat: Object to make group repeatable
repeat.min: Minimum number of group instances
repeat.max: Maximum number of group instances
description: Group description (shows in tooltip)
hint: Additional hint text (shows in tooltip)
actions: Array of action buttons for readonly mode
hidden: Hide field from form display but include in data (boolean)