<Root>

Start of documentation content

The <Root> is the top-level wrapper for programatic forms.

The only valid children are <Page>s.

Use of <Root>

<Formally licence="...">
  <Root>
    <Page id="page1"> ... </Page>
    <Page id="page2"> ... </Page>
  </Root>
</Formally>

<Root>'s props

PropAboutType
errorSummaryIntroHtml

Localisable HTML: Error Summary intro text

LocalisedHtml
fieldErrorPrefix

Localisable PlainText: screen-reader-only content before form field error messages to give some context to error messages for screen reader users.

E.g.

{
  en: 'Error',
}
LocalisedPlainText
fieldErrorSummaryHtml

Localisable HTML: Accessibilty Compass 'Error Summary' link error content.

Rendered as a link.

E.g.

{
  en: 'Error summary',
}
LocalisedHtml
fieldNextErrorHtml

Localisable HTML: Accessibilty compass next error content.

Rendered as a link.

E.g.

{
  en: 'Next Error',
}
LocalisedHtml
fieldPreviousErrorHtml

Localisable HTML: Accessibilty compass preceding error content.

Rendered as a link.

E.g.

{
  en: 'Previous Error',
}
LocalisedHtml
fieldRequiredLabel

Localisable PlainText: describes the * symbol as required for screen readers.

Kinda like alt-text for the * message on required form fields.

E.g.

{
  en: 'Required',
}
LocalisedPlainText
formBuilderId

The form builder id (optional).

Only necessary if you're loading a form from GetFormally.com.

string
formBuilderVersionId

The form builder version id (optional).

Only necessary if you're loading a form from GetFormally.com.

string
formRequiredDescription

Localisable PlainText: describes for all users (sighted, screen reader users, etc) that the form includes required fields which are marked with the * symbol.

E.g.

{
  en: 'Required fields are marked with an *',
  mi: 'Ka tohua ngā āpure ka hiahiatia ki te *',
}
LocalisedPlainText
hasAccessibilityCompass

Whether to enable the prototype accessibility feature 'Accessibility Compass'.

The Accessibility Compass is displayed on form fields with errors, providing quick links to the Error Summary, any preceding error, any next error, and the submit button.

(these four axes are why it was named a compass).

boolean
hasErrorSummary

Whether to display an error summary at the top of the page.

Error Summaries make it easier to find errors by providing a list of errors in the page.

This is because if there are only a few errors in a long page it can be difficult to find them, especially for screen reader users.

boolean
hasSubmitScreen

Whether success page/error screens are used after a form submission.

boolean
headingLevelOffset

For accessibilty reasons it's important that any headings (<h1>-<h6>) fit into the headings used in your page, including those outside of <Formally>.

The value of "auto" will detect any preceding heading and ensure headings in Formally fit. E.g. if the preceding heading is <h2> then Formally will use <h3>. If there is no preceding heading then with 'auto' Formally will use <h1>.

Leave this as "auto" unless you want to choose a specific heading level offset.

If you do wish to choose a specific heading level offset choose a number from 1-6.

HeadingLevel | "auto"
localeNames

Localisable Text: Locale picker locale names content.

{
  en: "English",
  cn: "Chinese (Mandarin)"
}
LocalisedPlainText
locales

An array of the enabled locale ids for the locale picker.

If a locale isn't in this list the localisable content won't be used.

This also affects the order of locales in the Locale Picker, and the default locale if the user's browser doesn't express a preference.

E.g.

["en", "mi"]
string[]
localeSelectLabelHtml

Localisable HTML: Locale selector label content.

E.g.

{
  en: 'Select language',
  mi: 'Tīpako reo',
}
LocalisedHtml
pageIndicatorHtml

Localisable HTML: page indicator content (progress indicator).

Displayed at the top of the page.

E.g.

{
  en: 'Page {pageNumber} of {totalPages}',
  mi: 'Wharāngi {pageNumber} o te {totalPages}',
}

See also the hasProgressIndicator boolean on each <Page> to enable it.

LocalisedHtml
publishedAtUTCms

When a form was published in UTC milliseconds.

number | false
removeAutoSuggestionLabelHtml

Localisable HTML: Removing an <AutoSuggest> item.

LocalisedHtml
submitErrorChildrenById

A list of ids of error components for display after a form submission.

E.g. an id of <Content> saying "try again later".

string[]
submitLabelHtml

Localisable HTML: Submit button content.

LocalisedHtml
submitPendingHtml

Localisable HTML: While waiting for the network after a submission this content will be used (and announced in an aria-live region).

LocalisedHtml
submitSuccessChildrenById

A list of ids of success components for display after a form submission.

E.g. an id of <Content> saying "thanks!".

string[]
updatedAtUTCms

When a form was updated in UTC milliseconds.

number
tags

A list of tags within the document.

DOCS TODO

Record<string, Tag>
meta

Arbitrary metadata on this node.

This is useful when developing custom controls as it allows you to pass down metadata/extensions.

MetaData
childrenById

Used to indicate children ids which should only refer to <Page> components.

If used in React this is non-editable.

string[]
formDefinitionSchemaVersion

Non-editable

It's the form schema version number so that if a breaking change is made to this schema format we can indicate changes.

Presently 1 is the only valid value.

1
hasChildrenById

Non-editable.

Used to indicate that this component has children.

true
hasTagsById

Non-editable.

Used to indicate that this component isn't a form field with tags by id.

false
id

Non-editable.

Root must be called "__root".

"__root"
isFormField

Non-editable.

Used to indicate that this component isn't a form field.

false
isMultichoice

Non-editable.

Used to indicate that this component isn't a multichoice form field like <Select>, <Radios> or <Checkboxes>.

false
pendingAttachments

Non-editable.

This is an Internal API that shouldn't be used by developers.

When using the SDK with JSX then React will mount components leaf-to-root, meaning that the parent node won't exist when the leaf is trying to attach itself.

So this is a queue of pending attachments by orphans listing the parents they want. Thankfully it's just data, tragedy averted.

{ from: string; to: string; }[]
type

Non-editable.

Type of component of "Root".

"Root"