Skip to content

The form element ​

<datum-form> renders a definition, validates the answers and raises the submission. Attributes carry the declarative part, JS properties take objects and functions, events report what happened, and methods let the page's own controls drive the form.

html
<link rel="stylesheet" href="datum-form.css">
<script type="module" src="datum-form.js"></script>

<datum-form src="/forms/intake.json" locale="auto" draft="intake"></datum-form>

The tables on this page are written from the element's own code, so they list every attribute and event the element has. The same list ships as attributes.json in the repository's docs/reference/ folder, for tools.

Attributes ​

Almost every attribute has a property of the same meaning, named under it where the spelling differs. The two exceptions are debug and allow-origins, which are attribute only: set them with setAttribute. An attribute takes text, so objects are written as JSON; the property takes the object itself.

Attribute and propertyWhat it does
definitionOne of definition or src is required. The property takes the object. Refused (datum-error, nothing replaced) while a src fetch is still loading: clear src first.
Takes JSON of a form definition. Default none.
srcFetched on connect; a later change refetches, and a form an earlier src brought is replaced. Refused (datum-error, nothing fetched) while a definition the page assigned is in place: clear definition first. A response longer than max-definition-bytes is refused before it is parsed.
Takes URL of a definition. Default none.
max-definition-bytes
maxDefinitionBytes
The longest definition read from src, in UTF-8 bytes, the cap every other import has; a longer one is reported as datum-error and not parsed. Anything but a whole number above 0 is reported and the cap stays.
Takes whole number of bytes. Default 2097152 (2 MiB).
modereadonly keeps the answers as sent.
Takes interactive | readonly. Default interactive.
localeThe starting locale, negotiated against the form's supported locales; auto takes the visitor's browser languages. Switching later never resets an answer.
Takes BCP 47 tag | auto. Default the form's default locale.
language-switcher
languageSwitcher
Shows the locale switcher in the form's header.
Takes boolean attribute. Default off.
chromeHeader, footer and other parts a host merges over the definition's own. The language-switcher, frame and frame-fixed attributes still apply beside it, merged in; where both give the same setting (a frame, a language-switcher part), the chrome's wins.
Takes JSON of the chrome parts. Default none.
frameA default the author's own pick beats, unless frame-fixed. Short for chrome.frame; with a chrome that names a frame, the chrome's frame is used instead.
Takes seamless | outlined | paper | a frame the binding defines. Default the binding's own.
frame-fixed
frameFixed
Makes frame beat the author's pick. Applies to the frame attribute, not to a frame the chrome names.
Takes boolean attribute. Default off.
heading-level
headingLevel
The level of the form's top heading; headings the form draws itself sit one level under it.
Takes 1 to 6. Default 1.
debug
attribute only
Logs journey diagnostics to the console.
Takes boolean attribute. Default off.
messagesValidation message templates by code. An entry wins over the message the definition authors for that code; codes it leaves out keep the definition's words.
Takes JSON of message overrides. Default none.
textsThe renderer's own strings (buttons, status lines).
Takes JSON of UI text overrides. Default none.
submitting-placement
submittingPlacement
Where the Submitting status line shows. Listing both draws a visual echo at the bottom so the line is announced once. Any other word is reported as an error.
Takes top, bottom, or both separated by spaces or commas. Default top.
confirmationPresent: an accepted submit shows the form's own confirmation, a notice with the reference the delivery's reply carries, if it has one. It never replaces a receipt the page set itself with setNotice. Worded through texts keys confirmationTitle, confirmationMessage and confirmationReference (English built in). Read when a submit is accepted; changing it rebuilds nothing.
Takes boolean attribute. Default off.
error-summary
errorSummaryPlacement
Where the error summary shows after an invalid submit; none leaves only the inline messages. Any other word is reported as an error.
Takes top, bottom, or both separated by spaces or commas; none. Default top.
data-sources
dataSources
The form paints first while its sources load. The property takes sources with functions.
Takes JSON of a data source set. Default none.
data-source-wait
dataSourceWait
all holds the form until every source has answered.
Takes none | all. Default none.
data-source-timeout
dataSourceTimeout
0 for no limit.
Takes milliseconds. Default 15000.
translationsThe host's translations of the form's texts; an entry overrides the definition's own translation of the same address.
Takes JSON of a translation catalog: locale, then kind (form, components, chrome, journeys, pdf), then the owner's id, then the property tree, with string leaves. Default none.
valuesSeeds the answers; setting later replaces them.
Takes JSON of initial answers. Default none.
host-context
hostContext
Facts about the visit the rules read, such as host.role. Plain JSON data only: a function, NaN or a Date is left out and reported as datum-error host-context.invalid. Changing it updates the form in place and keeps the answers typed so far. For display only: it is not sent with a submission, and a server judges host. rules with values of its own.
Takes JSON object of the values host. names read. Default none.
draftA key: answers auto-save under it (the browser's storage unless draft-store or the draftStore property says otherwise) and restore on return.
Takes storage key. Default none.
draft-store
draftStore
Where the draft key's draft is kept. server:<url> (on the page's origin, or one allow-origins lists; relative URLs read against the page) speaks four requests, <id> being the draft key: PUT <url>/<id> saves the draft as JSON, GET <url>/<id> answers it (404 when there is none), DELETE <url>/<id> removes it (404 counts as removed), GET <url> lists the drafts. local is the browser's storage. Anything else is reported as datum-error. A server on another origin is reported as datum-error and drafts stay in the browser. A draftStore object assigned from script wins; it is the route for headers, credentials, another origin or another protocol. Does nothing without draft, and nothing when features leaves drafts out.
Takes server:<url> | local. Default local (browser storage).
featuresPresent means only the listed features exist; minimal is a single-page form that renders, validates and submits. The attributes and properties of a feature can only narrow a listed feature, never enable one the list omits. What the page or the definition asks of a left-out feature is ignored with one console warning, its methods reject, and its files (the PDF module, the sandbox, the WebAuthn code, the server validator) are never requested. A word with a minus in front takes that feature out: all -drafts is every feature but drafts, and so is -drafts alone, since a list of only exclusions starts from all; an exclusion wins wherever it stands. A word that names nothing (a mistyped exclusion included) is reported as datum-error and left out, and a list holding one never starts from all, so a typo can only narrow. agent is opt-in: not part of all; write all agent to add it (the agent tools a browser assistant can call through WebMCP, and agentTools() / executeAgentTool() for page script, from a lazy chunk). Changing it rebuilds the runtime, and the answers typed so far carry over; an agent-only change only registers or withdraws the agent tools.
Takes space or comma list of journeys, print, translations, data-sources, drafts, server-validation, signing, pdf, wasm, agent; presets all, minimal; -name leaves one out. Default absent: every feature but agent.
agent-access
agentAccess
With the agent features token: the host enforces, the definition decides, or the host forbids. always: the host enforces, so the tools are registered whatever the definition says (the author's agentTools: off included). definition, the default: the definition decides, so root.configuration.agentTools allowed is live and off or absent is registered sealed (every call answers agent-off, except describe_form, which says the form is the person's to fill). never: the host forbids, so nothing is registered or loaded for this element. Without the token it does nothing. Changing it never rebuilds the form.
Takes always | definition | never. Default absent: definition.
pdfauto fetches datum-pdf.js beside the bundle on the first PDF. A loaded module is the pdfSupport property; a template resolver is the pdfTemplates property. Held to the page's origin: a URL on another origin is reported as datum-error and the attribute is treated as absent, unless allow-origins lists that origin; the property may name any.
Takes auto | URL of the PDF module. Default unset (no PDFs).
pdf-theme
pdfTheme
The theme the PDF is drawn with when the render call and the layout name none; it outranks the binding's suggestion.
Takes PDF theme id (default, or a registered id). Default unset: the PDF theme the form's binding suggests, else default.
pdf-unknown-components
pdfUnknownComponents
What a PDF does with a component it has no rendition for: ignore draws it generically and says nothing, warn does the same and reports component.unknown, fail rejects the PDF.
Takes ignore | warn | fail. Default warn.
formula-errors
formulaErrors
What a rule formula that cannot be read does: fail refuses the form, warn drops the rule and says so.
Takes fail | warn. Default fail.
risky-patterns
riskyPatterns
Whether a regular expression that could run away is refused.
Takes refuse | allow. Default refuse.
wasmauto fetches datum-wasm.js beside the bundle and runs the validation sandbox in the page, for development and testing. In production the server validates. A page that imported the module assigns wasmValidationHost; plugins and external data are properties. Held to the page's origin: a URL on another origin is reported as datum-error and the attribute is treated as absent, unless allow-origins lists that origin; the property may name any.
Takes auto | URL of the sandbox module. Default unset.
wasm-log-level
wasmLogLevel
How much the sandbox's run log keeps; the log arrives on datum-wasm-validated.
Takes off | error | warn | info | debug. Default warn.
wasm-timeout
wasmTimeout
How long the page waits for the sandbox module to load; 0 waits without limit. A module that never loads blocks the submit with an error.
Takes milliseconds. Default 15000.
signing-scope
signingScope
What a signed submission covers. Providers are the signingProvider(s) and pdfSigner properties (functions); the attribute sets the scope inside the signing property.
Takes envelope | submission | values. Default envelope.
signing-placement
signingPlacement
Where the signature sits in the delivered submission; the attribute sets the placement inside the signing property.
Takes embedded | wrapper. Default embedded.
sign-with
signWith
The id of the provider every submit signs with; no provider of that id refuses the submit (signing.providerMissing).
Takes provider id. Default none.
change-on
changeOn
When a typed value counts as settled for datum-change: input reports after change-debounce ms of quiet or on leaving the field, commit only on leaving the field. Any other word is reported as an error.
Takes input | commit. Default input.
change-debounce
changeDebounce
The quiet time for change-on input; 0 reports every write.
Takes whole milliseconds. Default 300.
journeyWhich journey runs: an id, form for the whole form on one page, or journey for the definition's default journey. Changing it restarts the journey over the answers typed. On a definition that has journeys, form still loads the journeys runtime (the journey can be switched later without a rebuild), so a missing runtime file shows the error card even then.
Takes journey id | form | journey. Default the definition decides.
pageOpens the journey on that page when the person may reach it (a deep link, a resume point); nextPage and previousPage move it, and reading the property gives the page shown.
Takes page id. Default the journey's first page.
validate-url
validateUrl
Where a journey's server check posts, as the { document, scope, pageId } delivery a Datum host's POST /api/submissions/validate takes; a serverValidator property wins over it and is the custom validator. Held to the page's origin: a URL on another origin is reported as datum-error and the attribute is treated as absent, unless allow-origins lists that origin; the property may name any.
Takes URL. Default none.
validate-timeout
validateTimeout
How long a journey's server check may take before the service counts as unavailable. Read when the form is built: changing it rebuilds the runtime, and the answers typed so far carry over.
Takes whole milliseconds; 0 for no limit. Default 10000.
allow-origins
attribute only
The other origins the wasm, pdf, draft-store and validate-url attributes may name. A word that names no origin (*, a bare host) is reported as datum-error and left out. Changing it applies an attribute it now allows and drops one it no longer does.
Takes space-separated origins, each written as a URL (https://cdn.example). Default none: the page's own origin only.

Properties without an attribute ​

Functions, registries and custom objects are set from script.

PropertyWhat it is
pluginsPlugins for this form alone, beside those the page registered with plugins.register: FormPlugin objects whose components join the catalogue, whose validators run after the field constraints, and whose hooks, submission handlers, PDF renditions, sandbox modules and data sources the form takes up. A property only. Assigning rebuilds the form and keeps the answers typed so far.
componentDefinitionsComponent types beyond the standard catalogue, each drawn by its definition's adapter; a type with a standard one's name replaces it. Assigning rebuilds the form and keeps the answers typed so far.
themes
pluginRegistry
The registries the element resolves through: themes for the pdf-theme id, pluginRegistry for the page's plugins. Each is the page's shared one (the themes and plugins exports) unless a host hands the element its own. A plugin registered after the element connected is taken up: the form is rebuilt, and the answers typed so far stay.
binding
assets
colorScheme
The design-system binding the form is drawn by (a LiveBinding, or the id of one registered with bindings.register; Datum's when left out), the files that binding needs (stylesheets, fonts, scripts), and light or dark.
dataSources
messages
texts
values
Object forms of the attributes of the same name; the property takes functions where the attribute cannot.
signingProviders
pdfSigner
pdfSignature
signing
Functions: a passkey provider, a hardware-token signer.
serverValidator
draftStore
wasmValidationHost
wasmPlugins
wasmExternalData
Custom objects behind validate-url, draft and wasm.
pdfSupport
pdfTemplates
A loaded PDF module and a template resolver behind pdf.
readyRead-only promise: resolves after datum-ready for the current definition (at once when the form is ready already), rejects with the build error (the journeys runtime that did not arrive, a definition the runtime refused), is not rejected by a build a newer request replaced, and is a fresh promise after the next build or Retry. With no definition it settles once one is set and built.

printTheme takes the theme a printed form is drawn with; Datum's plain one applies when it is left out. See Print.

Events ​

Every event bubbles and is composed, so one listener on the page hears every form, even from inside another element's shadow tree. Listen on the form or on document. The event's data is in event.detail.

EventWhen, and what detail carries
datum-submitAn accepted submission; detail carries the answers, and detail.submissionKey the attempt's key, which the page sends beside the document ({ document, submissionKey }) and again unchanged when it retries the delivery. detail.trigger is "agent" when a browser assistant's submit tool started it, and detail.agent (an AgentProvenance) says which answers the assistant's tools wrote last; both are absent where the element's tools were never live: a form that has only ever been sealed adds none.
datum-changeA settled value change.
datum-validatedValidation finished.
datum-errorA problem the page should know of: { code, message, cause? }. The code names the cause (definition.load, definition.too-large, sandbox.unavailable); the message is words to show. An unreadable definition, a sandbox that never loaded.
datum-binding-errorThe binding or its files failed: detail.hook says where (assets: a stylesheet or script of the design system could not be had, with detail.url, and an alert takes the form's place; binding: an id nobody registered; render, ready, focus and self-check: a hook of the binding), detail.message why. Bubbles and is composed.
datum-form-actionA button was pressed whose action the element does not act on itself; the page hears it and decides. detail is { componentId, action, signature?, journey? }: the button's id, its configured action as written, its signature option. The element handles submit and download buttons, a journey's own Submit, and a pdf button while it can make a PDF (as datum-submit, datum-download and datum-pdf), and stops those; any other action, and a pdf button when no PDF module is set, reaches the page here.
datum-downloadCancelable; an accepted submission saved as a file.
datum-pdfCancelable; a PDF was made (the PDF button, downloadPdf() or a browser assistant's download_pdf tool); cancelling takes the file over, so the page sends it where it wants. detail.trigger is "agent" for the assistant's tool, and detail.agent is the AgentProvenance account, absent where the element's tools were never live: a form that has only ever been sealed adds none.
datum-printCancelable; print() routed elsewhere if cancelled.
datum-readyThe form is built and drawn; one microtask after the definition lands for a plain form, one chunk load later for the first journey form on a page. The ready promise settles with it.
datum-page-changeThe journey moved to another page.
datum-locale-appliedA locale took effect; detail.locale is its code.
datum-locale-rejectedThe person picked a language in the form's own switcher that the form does not declare. detail is { locale, message }: the code picked and the runtime's reason. The switcher has been put back to the form's current language, and nothing else changes.
datum-wasm-readyThe validation sandbox loaded.
datum-wasm-validatedThe sandbox finished a check.
datum-agent-actionWith the agent feature: a browser assistant's tool call finished. detail names the tool, its outcome and what it changed; see Assistants.
datum-agent-sessionWith the agent feature: an assistant's session began, ended, was stopped or went idle; detail.phase says which.
datum-agent-toolsWith the agent feature: the tools were registered, sealed or withdrawn; detail.registered, detail.access and, when not registered, detail.reason say which.
datum-warningSomething taken, but not whole: detail.code draft.dropped says restoreDraft() left out answers the form cannot hold (an object or a list in a single-valued field), with detail.count and detail.addresses (the first few); the rest is restored.

Event details ​

Every event is bubbles and composed. Only datum-download, datum-pdf and datum-print are cancelable.

datum-submit ​

See Submissions and replies: accepted, submission, errors, result, signed, submissionKey, trigger, agent and waitUntil.

datum-change ​

KeyValue
pathThe value path that was written, such as email or billing.street. undefined when the event names none.
valueWhat the path now holds.
valuesThe form's answers as a whole, one entry per value path. Fields a journey page owns for itself are not in it.

The event is not raised on every keystroke. See When a change is reported.

datum-validated ​

KeyValue
errorsThe errors after validate() ran: a list of the entries below, empty when the form is valid.

Each entry of errors is shaped like this. submit and setErrors return the same entries.

KeyValue
idAn identifier of the entry, unique within the list.
codeThe error code, such as required.
messageText, when the stage that raised it supplied one.
componentIdThe component the error is on, when it is on one.
pathWhere the answer is stored, as { segments: [{ key, index? }] }, when the error is on a row or a nested answer.
stageThe stage that raised it, such as host for an error the page set with setErrors.
severityerror (the default, blocks), warning or info.
sourceclient, wasm, server or custom.
parametersValues the message names, such as { min: 3, count: 2 }.

datum-ready ​

KeyValue
runtimeThe engine's runtime object for the form just built. It is the engine's own surface and is not documented on this site: prefer the element's methods.

datum-error ​

KeyValue
codeA stable name for the cause, such as definition.too-large or sandbox.unavailable. Match on this. The codes page lists them.
messageWhat went wrong, in words, for showing. It may be reworded between releases.
causeThe thrown value, when there was one.
sourceIdOnly for a data source that failed: its id.
componentIdOnly for a data source that failed: the component that names it.

datum-warning ​

KeyValue
messageWhat was taken only in part.
codedraft.dropped: a restored draft held answers the form cannot hold, and the rest was restored.
countHow many answers were dropped.
addressesThe first few of them, as dotted paths.

datum-page-change ​

KeyValue
journeyId, pageIdThe journey and the page the person is now on.
fromPageIdThe page they left, or null when the journey has just started.
directionWhy: forward (Continue), back, jump (a page already reached), change (a Change link on a Check answers step), error (the page holding an error after a blocked submit), start, resume (a draft restored) or redirect (the page asked for with page cannot be reached with these answers; pageId is where the person is instead).
index, totalThe page's place on the path as the answers draw it now, counting from 0, with every page on it.
titleThe page's heading in the form's language.
kindquestions or exit.
errorCountThe blocking errors the page shows.

datum-locale-applied and datum-locale-rejected ​

EventKeyValue
datum-locale-appliedlocaleThe language that took effect, whether the locale attribute negotiated it or the switcher picked it.
datum-locale-rejectedlocaleThe language the switcher offered that the form does not declare. The switcher has been put back to the form's current language.
datum-locale-rejectedmessageThe reason, for a page that wants to show it.

datum-download ​

Cancelable. Fires before the browser is handed the file of an accepted submission. Cancelling takes the file over, for example to upload it, and nothing is downloaded.

KeyValue
submissionThe envelope, or the signed wrapper around it under the wrapper signing placement.
fileNameThe name the file would be saved as.
jsonThe exact text the file would hold.

datum-pdf ​

Cancelable. Fires before the browser is handed a PDF made by the PDF button, downloadPdf() or an assistant's tool. Cancelling takes the bytes over.

KeyValue
bytesThe PDF, as a Uint8Array.
fileNameThe name it would be saved as.
layoutIdThe layout that drew it.
layoutChoicecondition when no layout was named and the first layout whose condition held was used.
pageCountThe number of pages.
warningsWhat the PDF kernel had to say, a list.
signaturePresent when the file was signed: what was signed.
trigger, agentAs on datum-submit.

datum-print ​

Cancelable. Fires before the print dialog opens. Cancelling takes the document over, for example to send it to a PDF service, and nothing is printed.

KeyValue
htmlThe complete document that would print.
themeThe id of the print theme it is drawn with.
fellBackPresent when the print theme asked for was set aside for the basic one: the reasons, a list of strings.

datum-wasm-ready and datum-wasm-validated ​

EventKeyValue
datum-wasm-readyhostThe loaded sandbox host.
datum-wasm-validatedblockedWhether the sandbox's verdict blocked the submit.
durationMsHow long the run took.
unknownFieldsThe setting the run used for keys the form does not define: strip, keep or reject.
logLevelThe level the run log kept, when one was set.
values, externalDataWhat the run was given.
outcomeThe sandbox's answer, when it gave one. See Your own server.
executionErrorWhy it gave none.
logsThe run log entries, for the page to forward to a console or a logger.

datum-binding-error ​

KeyValue
hookWhere it failed: assets (a stylesheet or script of a design system did not load), binding (an id nobody registered), or one of the binding's own hooks such as render, ready, focus and self-check.
messageWhy.
idThe field's instance key or component id, when one field's problem.
urlThe file, for assets.
problemsA list of reasons, when the failure had several.

datum-form-action ​

KeyValue
componentIdThe button's component id.
actionThe button's configured action, as written.
signatureThe button's signature option, when it has one.

A button with the action submit or download, and a journey's own Submit, is handled by the element, which raises datum-submit and datum-download, so the page does not hear it here. A pdf button reaches the page as datum-form-action only when the element has neither a pdf attribute nor a pdfSupport property to serve it. The event is not a way to attach a button action of your own: the actions a button can have are submit, download and pdf.

When the form is ready ​

A form is built a moment after it gets its definition: a microtask after definition is assigned or src has loaded, and one chunk load later for the first journey form on a page, because journeys run from a file of their own. datum-ready is raised when the form is built and drawn, and form.ready is a promise for the same moment.

js
const form = document.querySelector("datum-form");
form.definition = definition;
await form.ready;           // resolves once datum-ready has been raised
form.setLocale("fr");

ready resolves once datum-ready has been dispatched for the build, and at once when the form is ready already. It rejects with the reason when a build fails: the journeys file did not arrive, or the runtime refused the definition. A build that a newer assignment replaces rejects nothing, and ready follows the form becoming ready rather than one build. After a failure the next build, by Retry or a new definition, gives a fresh promise. With no definition it settles once one is set and built. An unawaited rejection is not reported as an unhandled one. Every change that rebuilds the form raises datum-ready again; read ready again for the next one.

The methods that return a promise (validate, submit, submitAndDownload, renderPdf, downloadPdf, print, the draft methods, nextPage, previousPage and goToPage) wait for a build under way and then run. Two methods answer at once and cannot wait, so they throw while the form is building:

MethodBefore the form is built
setErrorsThrows "the form is still building; call this after datum-ready".
setLocaleThe same. The locale is kept, and the form is built in it.

Both also throw <datum-form> has no form yet when there is no definition at all. form.definition = d; form.setLocale("fr") in one tick therefore throws: await ready between them. The locale attribute has no such limit; it applies when the form is built.

What keeps the answers and what starts afresh ​

Some settings are read when the form is built, so changing one builds the form again: dataSources, translations, draft, draftStore, plugins (and a plugin registered on the page later), componentDefinitions, features, formulaErrors, riskyPatterns, the signing properties, validateTimeout, dataSourceTimeout, and wasm or wasmValidationHost when the sandbox appears or goes. A rebuild for the same form keeps what the person typed and the language they chose, and the next submit sends those answers. values assigned in the same change win over the typed answers. Errors already shown are cleared until the next check, and a journey goes back to the first page the person may open, with the answers kept. Each rebuild raises datum-ready again.

The other settings, such as messages, texts, locale, frame, chrome, mode and binding, take effect in place, without a rebuild. So does hostContext: the rules that read host. are worked out again over the answers typed so far, and no datum-ready is raised.

Assigning definition, or a src that loads, starts the form afresh, even when it is the same object assigned again: the typed answers go, and values seeds the new form. Assigning is still a way to clear a form, but reset() is the plain one.

reset() takes the form back to how it first opened for its current definition. It clears what the person typed, the errors and notice on show, which fields were touched, and a journey's place. It applies the values the page assigned again. The language the person chose, the definition and every other setting stay. The form is built again, so datum-ready is raised again, and then one datum-change tells the page the answers are cleared: it has no path, and values holds the form's answers now. reset() resolves after that event. It does nothing on a form with no definition.

reset() does not touch a stored draft. It writes none and deletes none. The first change after it arms the autosave, which then saves the form as it stands, so the draft is replaced by the cleared form. To drop the draft too, call clearDraft() as well. See Drafts.

Setting errors and notices ​

setErrors(errors) takes a list. Each entry:

KeyMeaning
codeRequired. The error code, such as required or a code of your own.
messageText for the error. Its {name} slots are filled from parameters.
componentIdThe component the error is on. Without it, and without a path, the error belongs to the form as a whole and is listed in the summary only.
pathA value path, such as items[1].sku for a field in the second row of a data grid, or billing.street. A path without an index names the answer's field, so the error is placed on the component stored there. A path with an index places it on that row.
severityerror (the default, blocks), warning or info. A warning or note is shown and does not block.
sourceclient, wasm, server or custom. Defaults to server.
parametersValues for the message's {name} slots, such as { max: 3 }.

The errors replace those the form held, are shown on their fields and in the summary, move focus to the first, and are returned as the entries described under datum-validated (with stage: "host"). The next validate() or submit() replaces them, and setErrors([]) clears them. In a journey, an error the server reported stands through the page's own checks until its answer changes, and the person is moved to the first page that holds one.

setNotice(notice) takes this object, or undefined to clear:

KeyMeaning
kindsuccess (the default), info, warning or error. An error is announced at once; the others are announced politely.
placementA list of "top" and "bottom": the ends of the form it is drawn at. Absent or empty means ["top"]. At both ends, the top copy is the one announced.
title, messagePlain text, or { "default": "...", "locales": { "fr": "..." } } to follow the language.
detailsA list of { label, value }, such as { label: "Reference", value: "GC-48213" }. label can be worded per language; value is a plain string.
dataThe receipt as plain JSON, such as { "reference": "GC-48213" }. It is never drawn by itself: a printed header or footer reads it as {{receipt.reference}} (see Print). A notice with only data draws nothing.

The notice is drawn where the error summary goes, takes focus, and is printed with the form. The next submit clears it. The notice property reads what was last set.

When a change is reported ​

datum-change reports a value once it has settled, not on every keystroke. Two attributes decide when:

AttributeDefaultMeaning
change-oninputinput: a typed value is reported after change-debounce milliseconds without another keystroke, or when the field is left, whichever comes first. commit: a typed value is reported only when the field is left.
change-debounce300The quiet time for change-on="input", in whole milliseconds. 0 reports every write.

A pick (a select, a checkbox, a radio) and a value the page writes are reported at once. A value still waiting is reported before datum-submit, so the answers a listener holds match what is submitted. Any other word for change-on is reported as datum-error.

The confirmation ​

The confirmation attribute is a boolean. With it present, an accepted submit shows a notice with the form's own words: "Your form was submitted", a message, and a line with the reference when the delivery's reply carries one. The rule for the reference, and when the notice does not appear, is under After acceptance. A notice the page set with setNotice is never replaced by it, and a download never shows it. The three sentences are texts keys, listed on The form's own words.

Origins and size ​

Four attributes name a URL the page would load code from or send answers to: wasm, pdf, draft-store and validate-url. In markup they reach places a script does not, so each is held to the page's own origin. An attribute that names another origin is reported as datum-error and ignored, unless allow-origins lists that origin.

allow-origins is a space-separated list of origins, each written as a URL: allow-origins="https://cdn.example https://forms.example". A path after the origin is ignored. A word that names no origin, such as *, a bare host or a data: URL, is reported as datum-error and left out. It is read as an attribute only: set it with setAttribute. Changing it applies an attribute it now allows and drops one it no longer does, so it can be set after the others.

The rule has these edges:

  • The properties are not held to it. A script that sets pdfSupport, wasmValidationHost or draftStore already runs on the page, and may name any origin.
  • src is not covered. It is fetched with a plain fetch, so the browser's CORS rules, the page's connect-src and the server's headers decide whether another origin may serve a definition. The fetch carries no headers and no credentials. A definition behind a login is fetched by the page and assigned to definition.
  • src and definition are used one at a time. While a src fetch is loading, an assigned definition is refused, and while a definition is assigned, src is refused. Both are reported as datum-error, and nothing changes. Clear one before setting the other.

max-definition-bytes caps the size of a definition read from src, in UTF-8 bytes. The default is 2097152 (2 MiB). A response that declares a longer length is refused unread, a body is read only as far as the cap, and a longer one is reported as datum-error and not parsed. The value must be a whole number above 0, or it is reported and the cap stays. A definition the page assigns is not held to it.

Read-only properties ​

PropertyHolds
readyThe promise described under When the form is ready.
errorsThe errors the form holds now, as under datum-validated. Empty before the form is built.
noticeThe notice last set with setNotice.
submittingWhether a submit is in flight, from the submit until every waitUntil promise has settled. Also reflected as the submitting attribute, for a stylesheet to use.
activeLocaleThe language the form is showing now: what locale negotiated to, or what the switcher picked. undefined before the form is built.
rendererThe inner <datum-form-renderer> element.
runtimeThe engine's runtime object, the same one datum-ready hands out. It is the engine's own surface and is not documented on this site.

Methods ​

MethodDoes
validate({ focus })Runs every check, reports the errors as datum-validated and resolves with them. Focus moves to the first error unless focus is false.
submit({ signWith, signing })Validates, locks the form and raises datum-submit. Resolves with the same detail the event carries. A second call while one is in flight joins it; a call that asks for something different, or one made from inside a datum-submit listener, rejects.
submitAndDownload()Submits and saves the submission as a JSON file in one step: the signed document when there is one, otherwise the submission. A rejected submit shows its errors and saves nothing. For a PDF, use downloadPdf().
setErrors(errors)Shows the server's errors (code, message, componentId, path, severity, parameters) on their fields and in the summary, and returns them as shown. setErrors([]) clears them. Throws until the form is built: see When the form is ready, and Setting errors and notices.
setNotice(notice)Shows a notice with a kind, a title, a message and details, such as a confirmation number. setNotice(undefined) clears it, and so does the next submit.
reset()Clears the answers, errors, notice and journey position, and applies the values seed again. The language stays. Raises datum-ready and one datum-change, and resolves after them. A stored draft is left alone. See What keeps the answers and what starts afresh.
setLocale(locale)Switches the form's language. Throws for a locale the form does not support, and until the form is built. See Languages.
nextPage(), previousPage()Continue and Back on a journey, from the page's own controls. Each resolves with where the form went or, with ok: false, the reason it stayed.
goToPage(pageId)Opens a journey page the person has already reached, such as from a task list. Refused for a later page.
journeys()The journeys the definition declares, for a page that offers a choice. See Journeys.
presentationValues()The answers to fields a journey page owns for itself, which are kept in drafts and never sent in a submission.
hasDraft()Whether a draft is stored under the draft key.
saveDraft()Saves the answers under the draft key now, without waiting for the autosave. Resolves with the saved draft's summary.
restoreDraft()Restores the stored draft after checking it against the form. Rejects with a coded error when there is none or it does not fit.
clearDraft()Deletes the stored draft. See Drafts.
pdfLayouts()The PDF layouts the definition declares, for a page that offers a choice.
renderPdf(options)Draws the PDF from the current answers and resolves with its bytes. Loads the PDF kernel first when pdf names one.
downloadPdf(options)Draws the PDF and hands it to the person. See PDFs.
print(options)Opens the browser's print dialog with the form's print rendition. See Print.
agentTools(), executeAgentTool(name, input)With the agent feature: the tools a browser assistant is offered, and one of them run from page script. See Browser assistants.

The ready property is a promise that resolves once the current definition is built and drawn, and rejects with the reason when it could not be. See When the form is ready.

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