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)

Colour Picker

HTML5 colour picker for selecting hex colour values. Stores colours in uppercase hex format (#RRGGBB). Supports both single and multiple colour selection.

Multiple Colours: Set multiple: true to create a colour palette. Use minCount and maxCount properties to control the number of colours.

Schema Definition

Preview

Readonly Mode

Properties Reference

type: "colour" (required)
key: Unique identifier (required)
label: Display label for the field
description: Help text (shows in tooltip)
required: Whether the field is required (boolean)
default: Default hex colour value (e.g., "#0066CC")
multiple: Allow multiple colours (boolean)
minCount: Minimum number of colours (for multiple)
maxCount: Maximum number of colours (for multiple)
hint: Additional hint text (shows in tooltip)
hidden: Hide field from form display but include in data (boolean)

Slider (Linear Scale)

Interactive slider control for selecting numeric values within a defined range. Linear scale provides uniform spacing between values, ideal for most use cases like volume, brightness, or percentage controls.

Linear vs Exponential: Use scale: "linear" (default) for uniform value distribution. Use scale: "exponential" for values spanning multiple orders of magnitude (e.g., audio frequencies).

Schema Definition

Preview

Readonly Mode

Properties Reference

type: "slider" (required)
key: Unique identifier (required)
min: Minimum value (required, number)
max: Maximum value (required, number)
step: Increment step (optional, default: 1)
scale: "linear" or "exponential" (optional, default: "linear")
label: Display label for the field
description: Help text (shows in tooltip)
required: Whether field is required (boolean)
default: Default slider value
multiple: Allow multiple sliders (boolean)
minCount: Minimum number of sliders (for multiple)
maxCount: Maximum number of sliders (for multiple)
hint: Additional hint text (shows in tooltip)
hidden: Hide field but include in data (boolean)

Slider (Exponential Scale)

Slider with exponential (logarithmic) scale, perfect for values that span multiple orders of magnitude such as audio frequencies (20 Hz to 20 kHz), file sizes, or scientific measurements.

When to use exponential scale: Use exponential scale when the value range spans multiple orders of magnitude (e.g., 20-20000). This provides better control over smaller values while still reaching larger values.

Schema Definition

Preview

Readonly Mode

Use Cases for Exponential Scale

Audio Frequencies: 20 Hz to 20,000 Hz (human hearing range)
File Sizes: 1 KB to 1 GB (storage allocation)
Time Intervals: 1 ms to 1000 seconds (timeout settings)
Zoom Levels: 0.1x to 100x (image/map zoom)
Scientific Measurements: pH scale, Richter scale

Slider (Decimal Values)

Slider with decimal step values, ideal for temperature controls, measurement adjustments, or any scenario requiring sub-integer precision. The step property controls the increment precision.

Decimal Precision: Set step: 0.5 for half-unit increments, step: 0.1 for tenth-unit increments, etc. The displayed value automatically formats to match the step precision.

Schema Definition

Preview

Readonly Mode

Common Decimal Step Values

step: 0.1 - Tenth-unit precision (e.g., 1.0, 1.1, 1.2)
step: 0.5 - Half-unit precision (e.g., 0.0, 0.5, 1.0)
step: 0.25 - Quarter-unit precision (e.g., 0.0, 0.25, 0.5)
step: 0.01 - Hundredth-unit precision (e.g., 1.00, 1.01, 1.02)

Slider (Multiple Values)

Multiple slider controls for managing arrays of values. Perfect for equalizers, multi-band adjustments, or any scenario requiring multiple related numeric inputs. Use minCount and maxCount to control the quantity.

Fixed Count Example: Set minCount: 5 and maxCount: 5 to create a fixed array of sliders, ideal for equalizers or preset configurations where the count should not change.

Schema Definition

Preview

Readonly Mode

Multiple Slider Use Cases

Audio Equalizer: Fixed bands (60Hz, 250Hz, 1kHz, 4kHz, 16kHz)
RGBA Color Channels: Red, Green, Blue, Alpha (0-255 each)
Time Segments: Daily schedule with hourly breakdowns
Performance Metrics: Multiple KPI sliders (speed, quality, cost)
Multi-Zone Controls: Temperature or volume per room/zone

Slider (Custom Step Values)

Slider with custom step increments for coarse-grained control. Useful for percentage controls that should snap to specific intervals like 10%, 20%, etc., or any scenario where fine-grained control is not necessary.

Custom Steps: Set step: 10 to allow only values divisible by 10 (0, 10, 20, 30...). This provides simplified controls and prevents accidental micro-adjustments.

Schema Definition

Preview

Readonly Mode

Custom Step Examples

step: 5 - Multiples of 5 (0, 5, 10, 15, 20...)
step: 10 - Multiples of 10 (0, 10, 20, 30...)
step: 25 - Quarter increments (0, 25, 50, 75, 100)
step: 50 - Half increments (0, 50, 100)

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 Colour" to show a text field for hex colour 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 Colour"},
    {"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 Colour (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)