Complete documentation for all form field types
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.
text renders as a
<textarea rows="1"> with
wrap="soft" so long values wrap visually instead of
scrolling horizontally. Newlines are still stripped β
getFormData() returns a single-line string just like
a native <input>. A character counter (used / maxLength) appears under the field when maxLength is set.
text with multiple: true renders as a
vertical list of chip rows: [β input π]. Each chip is
its own validated input; bin button removes the row. Add-row button
appears at the bottom when maxCount hasn't been hit.
Colors via CSS variables: Chip styling is driven
by --fb-chip-bg, --fb-chip-border,
--fb-chip-text, and --fb-chip-dot β set
them in your own stylesheet (e.g. scoped by
[data-field-key="β¦"]) to give different fields
different palettes without schema changes.
true (required for
this rendering)
1; use 0 for an initially empty
list)
minCount
.fb-chip β single chip row container.fb-chip-dot β leading marker dot.fb-chip-input β the editable input.fb-chip-remove β bin button--fb-chip-bg β falls back to
--fb-background-color
--fb-chip-border β falls back to
--fb-border-color
--fb-chip-text β falls back to
--fb-text-color
--fb-chip-dot β falls back to
--fb-primary-color
Multi-line text input with configurable row height.
An expandable text input β also called "Π Π°ΡΡΠΈΡΡΠ΅ΠΌΡΠΉ Π²Π²ΠΎΠ΄" β that starts as a visually single-line field and grows automatically as the user types or presses Enter. No scrollbar appears; the field simply extends vertically to fit its content.
When to use: Prefer autoExpand: true
when the expected input length is unknown β short notes, search
queries, or comments that could be one line or many. Use a fixed
rows value when you want a predictable form height.
true β field starts at one row and grows
automatically (boolean)
Auto-expand textarea with multiline prefill data. When the form is rendered with existing content, the field automatically sizes itself to show all the text without a scrollbar.
Note: The height is recalculated on initial render so that prefilled multiline values are fully visible β no manual resize required.
Numeric input with min/max/step validation.
β/+ buttons around a narrow input
(see
Number (Stepper)).
number with stepper: true renders as a
compact pill: β button, narrow input, +
button. Native browser spinner arrows are hidden; the range-hint
chip under the field is hidden as well, since the pill is
self-describing.
When to use: Small bounded integers users tweak
by Β±1 (quantity, count, slide-count). For continuous or wide-range
numbers, keep the default
<input type="number">.
true (required for this
rendering)
β/+
clicks and on typed values
1; fractional values supported)
Dropdown selection with predefined options.
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.
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).
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.
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.
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.
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.
Segmented control (button group) for selecting a single value from a small set of options. Renders as a row of adjacent buttons where exactly one is active at a time.
When to use: Prefer Switcher over Select for 2β5
mutually-exclusive choices that users need to compare visually
(e.g. alignment, theme, size). For longer lists use
select instead.
{"value", "label"} objects (required). iconUrl (image URL or
data:image/... URI) and subtitle
(secondary line). When either is set the option renders as a
preset pill β see
Switcher (Preset Pills).
Switcher with a pre-selected default value. The
default property sets which option is active when the
form is first rendered without prefill data.
Default vs Prefill: The default is
used when no prefill is provided. If prefill data contains the
key, the prefill value takes precedence over the default.
Multiple mode renders a list of independent switcher controls, each
with its own selection. Users can add and remove switchers up to the
configured maxCount.
Multiple Switchers: Each switcher in the list
stores one value. The field data is an array of strings. Use
minCount and maxCount to control how
many switchers the user can have.
When any option has iconUrl or subtitle,
switcher switches from a tight segmented control to a
row of preset pills: icon on the left, label + subtitle stacked on
the right. Use this for visually-distinct presets (aspect-ratio,
template style, output format).
Field shape unchanged: Schema, data path, and
getFormData() output are identical to a plain
switcher β only the visual mode changes. Mix-and-match: some
options may omit iconUrl/subtitle; the
pill simply renders without them.
<img src> value β
typically a small SVG/PNG icon, or a
data:image/...;base64,... URI for inline assets.
label. Use for short clarifiers like
βsquareβ or β1080Γ1920β.
iOS-style pill toggle. Form data value is a real
boolean (true / false).
Renders as a single row: pill switch on the left, label and hint
stacked on the right.
Label position is unusual: Unlike other element
types, label renders inside the row (as the
bold title), not above it. hint is the grey subtitle
below the title. description still surfaces via the
small info-icon tooltip β use it for the longer explanation.
required is ignored: false is a valid
value.
true or
false β applied when no prefill value is provided
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.
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.
Control field visibility dynamically based on the value of another
field. The enableIf property allows you to show or hide
fields conditionally.
How it works: Add a enableIf object
with key (the field to watch) and
equals (the value that triggers visibility). The
field will only render when the condition is met.
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",
"enableIf": {
"key": "background_mode",
"equals": "image"
}
},
{
"type": "colour",
"key": "background_color",
"label": "Background Colour",
"placeholder": "#FFFFFF",
"description": "Pick a colour or enter a hex value (e.g., #FF5733)",
"enableIf": {
"key": "background_mode",
"equals": "colour"
}
},
{
"type": "textarea",
"key": "generation_prompt",
"label": "AI Generation Description",
"rows": 4,
"enableIf": {
"key": "background_mode",
"equals": "generate"
}
}
The enableIf property can be used with any field
type:
You can reference fields in nested containers using dot notation:
{
"type": "text",
"key": "city_specific_field",
"enableIf": {
"key": "address.city",
"equals": "New York"
}
}Or reference fields in repeatable containers using array indices:
{
"type": "text",
"key": "follow_up_question",
"enableIf": {
"key": "answers[0].rating",
"equals": "poor"
}
}required: true, but validation only
applies when visible.
Demo: Load the "Conditional Fields (enableIf)" 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.
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.
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.
Composite input combining a textarea, file attachments, and
@mention support. Output is an object with a
text string and a files array of resource
IDs.
Data format: The value is an object
{ text: string | null, files: string[] } where
files contains resource IDs returned by the
uploadFile handler. Use textKey and
filesKey to rename these output keys when needed.
{ extensions: string[] }
"text")
"files")
Table element for structured tabular data with cell merging support. Renders an editable grid where users can type into cells, add or remove rows and columns, and merge adjacent cells.
Data format: Table data is stored as an object
with a cells array (2D array of strings) and an
optional merges array describing merged cell regions.
Each merge specifies top, left (top-left
corner, 0-based) and bottom,
right (bottom-right corner, 0-based, inclusive).
false to disable cell merging.
{ cells?: string, merges?: string } β rename the
output keys (default:
{ cells: "cells", merges: "merges" })
["csv", "xlsx"]). When
omitted, file import is disabled. Requires
parseTableFile handler in config.
{
"cells": [
["Name", "Monday", "Tuesday"],
["Alice", "Meeting", "Dev"],
["Bob", "Standup", ""]
],
"merges": [
{ "top": 1, "left": 1, "bottom": 1, "right": 2 }
]
}
top/left (top-left
corner, inclusive, 0-based) and bottom/right
(bottom-right corner, inclusive, 0-based). Legacy
row/col/rowspan/colspan
format is auto-migrated.
Ctrl+M to merge selected cells,
Ctrl+Shift+M to split merged cell
importAccept schema property and
parseTableFile handler.
mergeAllowed: false to hide merge/split controls
and context menu
fieldNames to rename output keys when integrating
with specific backends
A table with cell merging and file import both disabled. Use
mergeAllowed: false to hide all merge/split controls
and omit importAccept to disable the import toolbar
button.
A table that uses custom output key names via the
fieldNames property. Useful when your backend expects
field names other than the defaults (cells and
merges).
Output format: With
fieldNames: { cells: "data", merges: "regions" } the
form data will contain
{ data: [...], regions: [...] } instead of the
default { cells: [...], merges: [...] }. Prefill data
must also use the custom key names.
cells and merges string properties
that rename the corresponding output keys
fieldNames
Renders static markdown content between input fields. The
markdown element has no value and produces no entry in
the submitted form data β it is purely presentational. Use it to add
headings, explanatory text, bullet lists, and links between fields.
A key is optional and, when provided, is used only as a
stable DOM identifier; it never appears in form data.
Supported markdown: headings (h1βh6),
**bold**, *italic*,
`inline code`, [links](url), bullet
lists (- item or * item), horizontal
rules (---), blockquotes (> text),
and paragraphs.
XSS-safe: All content is HTML-escaped before
rendering (<, >,
&). Link href values starting with
javascript:, data:, or
vbscript: are stripped. All generated
<a> elements get
target="_blank" rel="noopener noreferrer".
# Heading 1 β¦ ###### Heading 6
**bold***italic*`inline code`[link text](https://example.com)- bullet item or * bullet item
--- (horizontal rule)> blockquote text