Skip to content

Components ​

A form is a tree of components. Each one has a type name, written as type in the definition, and a configuration object for its settings. The builder's palette offers the types below. A person fills in the fields, reads the display types, presses the actions, and the containers arrange the rest.

json
{ "id": "email", "type": "text", "configuration": { "label": "Email", "maxLength": 80, "characterCount": true } }

Every component also carries an id, optional CSS classes, and rules that show, require or calculate it (see Rules and formulas).

Fields ​

Palette nameTypeWhat it isNotable settings
TexttextOne line of free text.placeholder, pattern with its own message, minLength, maxLength, characterCount (shows the count against maxLength), prefix and suffix, autocomplete, inputmode.
Text areatextareaSeveral lines of text.rows, plus the text settings above except prefix and suffix.
NumbernumberA quantity or an amount. The value stays a number in the record and in formulas.min and max (inclusive; see below), placeholder, prefix and suffix for a currency sign or a unit, autocomplete, inputmode.
DatedateA calendar day, kept as YYYY-MM-DD.min and max as YYYY-MM-DD (inclusive; see below), autocomplete. A design-system binding may draw it as month, day and year parts.
CheckboxcheckboxOne yes-or-no answer.Required means ticked.
File uploadfileA document or image from the person's device.accept, maxFileSizeMb per file, multiple, storage, and whether the files ride into a PDF as attachments.

Settings every field takes ​

These are keys of the component's configuration. The inspector offers the ones that apply to the type.

KeyTypeDefaultEffect
labeltextnoneThe label. A new field starts as "Untitled field".
descriptiontextnoneHelp text under the label.
tooltiptextnoneShort help on hover and focus.
placeholdertextnoneGhost text in an empty box. Text, text area, number and select.
requiredyes or nooffThe field must have an answer. For a checkbox, ticked.
hideLabelyes or nooffHides the label visually. It stays the field's accessible name.
disabledyes or nooffAlways disabled. A rule's enabledWhen does it conditionally.
minLength, maxLengthnumbernoneFewest and most characters of text and text area. A character is a code point, so an emoji counts one. A minimum above the maximum is ignored.
characterCountyes or nooffShows the characters left. Needs maxLength.
pattern, patternMessagetextnoneA regular expression the whole answer must match, and the message when it does not.
rowsnumber4Lines a text area opens with.
prefix, suffixtextnoneText before and after the box of a text or number field. Decorative: say the unit in the label too.
autocompletetextnoneAn HTML autocomplete token (name, email, bday-day, off).
inputmodetextnoneThe phone keyboard: numeric, decimal, tel, email, url, search, text or none.
spellcheck"true" or "false"browser'sWhether the browser spell-checks the box.
cssClasstextnoneSpace-separated classes added to the component's element.
messagesobjectnoneThe field's own wording per validation code: { "required": "Enter your email." }.
dataKeytextthe idThe name the answer is stored under (see Data model and data sources).
hiddenValueBehaviorexclude-from-submission, retain, clearexclude-from-submissionWhat is sent for the answer while the field is hidden: nothing, the answer, or no answer (see Answers of hidden fields).
pdf.rendition, pdf.exclude, pdf.attachtext, yes or no, yes or notheme's choice, off, offHow the field appears in a PDF, whether it is left out, and for a file field whether its uploads ride in as attachments.
print.on, print.show, print.notescreen or paper; always or answered; texton screen and paper, as on screenWhere the field is drawn, how it prints from the live form while a rule hides it, and the note printed beside it. Page breaks too: see Print.

A rule can also set a field's visibility, requiredness, enabled state and read-only state; see Rules and formulas.

Number and date bounds ​

min and max on a number or date component are inclusive. A number's are numbers (or numerals as text); a date's are YYYY-MM-DD. A bound that is not readable is ignored, and if min is above max both are ignored. The browser and the sandbox check them and raise these codes:

CodeWhen
number.min, number.maxThe number is below min or above max.
date.min, date.maxThe date is before min or after max.
json
{ "id": "age", "type": "number", "configuration": { "label": "Age", "min": 0, "max": 120 } }

When errors appear ​

The form's validateOn setting, on the root's configuration, says when a field is checked as its answer is committed. commitAfterError (the default) never checks a field on its first blur; once the field shows an error, or the person has tried to go on, it is checked again on each commit. submit judges answers only when the person tries to go on.

File upload storage ​

storage names where a picked file's bytes go. The built-in kind is base64: the bytes travel inside the form's values, so a submission is self-contained. An answer is an object { "storage": "base64", "name": "cv.pdf", "type": "application/pdf", "size": 48213, "data": "JVBERi0..." }, and a list of them when multiple is on. accept takes extensions, type/* or full MIME types, separated by commas. maxFileSizeMb is per file; left out, zero or unreadable means no limit. The browser and the sandbox both enforce accept and the size. A host that keeps files elsewhere supplies its own storage kind under another name, and the same field moves to it by changing that one setting.

Choices ​

Palette nameTypeWhat it isNotable settings
SelectselectOne choice in a drop-down.options, or a data source.
RadioradioOne choice from a few, all visible, in a fieldset with a legend.The same.
CheckboxescheckboxesSeveral choices. Stored as one object of booleans keyed by option.The same.

A new choice field starts with two options. Each option has a value (what is stored), a label and an optional description. A field that names a source in data.sourceId takes its options from it instead; see Data model and data sources.

Containers ​

Palette nameTypeWhat it does
FieldsetfieldsetA titled group of related fields with one legend. legendMark can mark the legend required or optional.
PanelpanelA framed section with a heading.
GridgridFields side by side. columns is a count (default 2, at most 12) or widths on a 12-track row. Every other container stacks its children one per row.
TabstabsLong forms split into named tabs, one entry in tabs each. The tab holding the first error opens on submit.
StepsstepsA multi-step form: step children shown one at a time, with a step indicator, Back and Continue. Rules can gate moving between steps.
StepstepOne page of a steps container. It belongs inside steps.
ContainercontainerA group whose id becomes a level in the data: email inside applicant is stored as applicant.email. scopeData set to false switches the nesting off.
Data griddataGridA repeating section: the fields inside it are the columns of one row, and the person adds, removes and reorders rows.
Button groupbutton-groupButtons laid out together in a row. It holds buttons only and adds nothing to the data.

Fieldsets, panels, grids, tabs, steps and button groups are for layout and add no level to the data. Tabs, steps and panels differ in what the person sees: tabs let them move freely between sections, steps walk them through in order, and a panel is a frame that is always open.

Children by container ​

A component's children is an object of named slots, each a list of components. The names depend on the container.

ContainerSlots
form, fieldset, panel, container, step, dataGridOne slot, content. For a data grid it holds the fields of one row.
gridcolumn_1 to column_N, one per column.
tabsOne slot per tab, named by the tab's id.
stepscontent, holding step components only.
button-groupcontent, holding buttons only.

A grid's columns is a count (3, equal columns) or widths out of 12 tracks: "8/4", "3 / 6 / 3" or [8, 4]. Equal widths read as equal columns, more than 12 columns are cut, and a value that cannot be read falls back to two equal columns.

json
{ "id": "name_row", "type": "grid", "configuration": { "columns": "8/4" },
  "children": { "column_1": [{ "id": "street", "type": "text", "configuration": { "label": "Street" } }],
                "column_2": [{ "id": "unit", "type": "text", "configuration": { "label": "Unit" } }] } }

Tabs are "tabs": [{ "id": "tab_1", "label": "First" }, { "id": "tab_2", "label": "Second" }] in the configuration, with a slot of the same id for each. The builder's inspector edits the first two tab labels only; add a third in the JSON tab by writing its entry and its slot.

Data grid settings ​

SettingMeaning
layoutauto (a table where the form is wide enough, stacked rows where it is not), table or stacked.
minRows, maxRowsFixed bounds. minRows defaults to 0; a maxRows below minRows reads as minRows. A grid with no maxRows holds at most 500 rows. A formula under rules.minRows or rules.maxRows can work either out from other answers.
initialRowsEmpty rows the form opens with when the grid has no entries yet. Default 1, held between minRows and maxRows.
canAdd, canRemove, canReorderWhich row buttons exist. Add and remove default to on, reorder to off.
showHeader, showRowNumbers, rowLabelThe column headings, the row numbers, and the row heading (Applicant ).
addLabel, removeLabel, emptyTextThe words on the buttons and the empty state.

Display ​

Palette nameTypeWhat it isNotable settings
HTMLhtmlInstructions, a consent notice or a heading between sections.tag (div, section, article, aside, p, span, h1 to h6, blockquote or pre; anything else reads as div) and content, localised and sanitised on every render: scripts, styles and event handlers are stripped, and a link or image address must be relative, http, https (or mailto and tel for a link), or an image data: URL.
ImageimageA picture: a logo or a diagram.src (an http(s) URL, a relative path or a small data:image URL), localised alt (empty means decorative), width, height.

Actions ​

Palette nameTypeWhat it doesNotable settings
ButtonbuttonActs on the form when pressed.action, variant, size, signature.

A button's action is one of:

ActionDoes
submitValidates and, when accepted, raises datum-submit with the canonical submission.
downloadSubmits, then hands the person the canonical submission as a JSON file. A rejected submit downloads nothing.
pdfChecks the answers as Submit does, then draws the form as a PDF through the page's PDF module and hands over the file. It does not submit. An error stops it and shows the summary; warnings and notes do not. See PDFs.

variant is one of primary, start, secondary, success, danger, warning, info, light, dark or link, and size one of sm, md or lg. The theme decides what each looks like. signature: "webauthn" on a submit button has the person's passkey or security key sign the submission (see Validation and the sandbox).

In PDF layouts ​

A PDF layout has its own palette: form field, text, image, signature, section, table, repeat, box, rule, spacer and page break. The signature block is the type pdf-signature: a real signature field the server or a viewer signs into, or a line to sign by hand. PDFs covers layouts.

Adding types and limiting the palette ​

The builder's palette holds the standard types plus anything a host adds. plugins.register(plugin) is the way to add types: it reaches every form and builder on the page and carries each type's palette entry. componentDefinitions on one element and the builder's componentTypes (palette entries only; a type from componentDefinitions needs one to appear on the palette) are shorter routes for one element. Components of your own covers what a definition holds and has a live example.

A type that is not one of the standard types needs a base, the standard type it reads as (a gcds-date reads as date). The builder writes it into the saved definition's kinds map, so validation and the PDF read the type correctly without the plugin's code. A type with no definition and no renderer shows a note naming it.

component-types on <datum-form-builder> restricts the palette. It takes a list of types separated by spaces or commas. A bare name keeps a type, a leading - drops one and a trailing * matches a prefix. Exclusions win.

html
<datum-form-builder component-types="text select radio checkboxes button"></datum-form-builder>
<datum-form-builder component-types="-acme-* -image"></datum-form-builder>

Icons come from an icon set. The builder draws its own, and @datum/icons-fontawesome registers Font Awesome Free solid glyphs as inline SVG when a page loads datum-icons-fontawesome.js before datum-builder.js.

MIT licence. Your forms, your data, your keys.