<Root>

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

The only valid children are <Page>s.

Use of <Root>

<Root
  formDefinitionSchemaVersion={1}
  hasErrorSummary={true}
  hasAccessibilityCompass={false}
  hasSubmitScreen={true}
  headingLevelOffset="auto"
  localeSelectLabelHtml={{
    en: 'Select language',
    mi: 'Tīpako reo',
  }}
  titleHtml={{
    en: 'Party Invite',
    mi: 'Tono whakangahau',
  }}
  pageIndicatorHtml={{
    en: 'Page {pageNumber} of {totalPages}',
    mi: 'Wharāngi {pageNumber} o te {totalPages}',
  }}
  submitLabelHtml={{
    en: 'Submit',
    mi: 'Tāpae',
  }}
  submitPendingHtml={{ en: 'Submitting...' }}
  removeAutoSuggestionLabelHtml={{
    en: 'Remove Suggestion',
    mi: 'Tango huatau',
  }}
  fieldErrorPrefix={{ en: 'Error:' }}
  fieldNextErrorHtml={{ en: 'Next error' }}
  fieldPreviousErrorHtml={{ en: 'Previous error' }}
  fieldErrorSummaryHtml={{
    en: 'Error Summary',
  }}
  errorSummaryIntroHtml={{
    en: 'Error: The following form fields have errors',
  }}
  fieldRequiredLabel={{ en: 'Required' }}
  formRequiredDescription={{
    en: 'Required fields are marked with an *',
    mi: 'Ka tohua ngā āpure ka hiahiatia ki te *',
  }}
  formBuilderId="b330be40-49af-43fa-a947-53587fb72513"
  formBuilderVersionId="e17edf55-f927-4f15-aba1-22b55b9328c6"
  publishedAtUTCms={0}
  updatedAtUTCms={0}
  locales={['en', 'mi']}
  localeNamesHtml={{
    en: {
      en: 'English',
      mi: 'Te reo Māori',
    },
    mi: {
      en: 'English',
      mi: 'Te reo Māori',
    },
  }}
  submitSuccessChildrenById={['thanks']}
  submitErrorChildrenById={[]}
  tags={{}}
>
  <Page />
  <Page />
  <Page />
</Root>

<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.

Can be short.

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"
localeNamesHtml

Localisable HTML: Locale picker locale names content.

Note: This is not the usual localisable content data structure.

If it was conventionally structured like {en: "English", mi: "Maori"} then locales couldn't describe others in their own locale.

Instead the structure is as,

{
  en: {
     en: "English",
     cn: "Chinese (Mandarin)"
  },
  cn: {
      en: "英语 (English)",
      cn: "中文"
  }
}

So that cn can describe en using cn words.

Record<string, 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

Informational metadata about when a form was published in UTC milliseconds.

Doesn't need to be accurate.

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[]
titleHtml

Localisable HTML: form title.

E.g.

{
  en: "English form title",
  mi: "Te Reo form title",
}
LocalisedHtml
updatedAtUTCms

Informational metadata about when a form was updated in UTC milliseconds.

Doesn't need to be accurate.

number
tags

A list of tags within the document.

DOCS TODO

Record<string, Tag>
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
type

Non-editable.

Type of component of "Root".

"Root"