Custom Controls

Intro

This is an SDK feature and it requires a licence. Please contact support for a licence.

Note: if you just want to theme CSS in Formally see the Theming page.

Use of the controls prop

import { Formally, ControlsProps } from 'formally';

type TextProps = ControlsProps['Text'];

const MyCustomText = ({ label, localisedMessages, field }: TextProps) => {
  // this component is just for demonstration purposes
  // it doesn't implement accessibility features
  return (
    <>
      {label}
      <input type="text" {...field} />
    </>
  );
};

export const MyForm = () => (
  <Formally
    formBuilderId="your-form-id"
    licence="your-licence-key"
    controls={{
      Text: MyCustomText,
    }}
  />
);

If you have your own Design System you can use it with Formally.

The full list of overrides available is still under development but the current list is:

Form fields

Text

Displays a text input field.

Upload

Displays a file upload field.

The onUpload prop (eg <Formally onUpload={myCustomUpload} />) can be used to customise the upload behaviour to send files to your own server.

Radios

A wrapper around radio fields.

Checkboxes

A wrapper around checkbox fields.

Select

Displays a <select> dropdown.

A wrapper around <option> and <optgroup>.

Range

Displays an <input type="range"> slider.

DateInput

Displays an date input with discrete fields for year, month, day, hours, minutes, and seconds.

AutoSuggest

Displays a file upload field.

The onAutoSuggest prop (eg <Formally onAutoSuggest={myAutoSuggest} />) can be used to customise the autosuggest behaviour to query your own APIs.

Errors

ErrorSummary

A wrapper around the error summary which displays a list of errors at the top of the page.

This feature is enabled by default.

ErrorSummaryItem

Displays each error summary item.

ErrorScreen

A wrapper around any errors that occur during form submission.

Error

Displays an individual field error.

ErrorAccessibilityCompass

The Accessibility Compass is a prototype accessibility feature.

The Accessibility Compass metaphor comes from the idea that each field with an error would also link to the 'preceding error' and/or 'following error' so that they can navigate directly between fields with errors without having to navigate back to the Error Summary.

This feature is disabled by default.

We're very keen to hear feedback about this feature.

Formally UI wrappers

Page

Displays a wrapper around the page content.

PageWrapper

Displays a wrapper around the page.

PageIndicator

Displays a message showing form progress e.g. 'Page 1 of 4'.

PageTitle

Displays a message for the page title.

FormRoot

A wrapper around the whole form

Buttons

ButtonGroup

A wrapper around the previous/next/submit buttons.

RepeaterButton

Displays a button for adding a repeating section of the form.

PreviousButton

Displays a button for navigating to the previous page.

NextButton

Displays a button for navigating to the next page.

SubmitButton

Displays a button for submitting the form.

SubmitPending

Displays a message while the form is being submitted.

CheckboxesGroup

Displays a <fieldset> around groups of checkbox options.

Checkbox

Displays a <input type="checkbox">.

RadiosGroup

Displays a <fieldset> around groups of radio options.

Radio

Displays a <input type="radio">.

SelectOptionGroup

Displays an <optgroup>.

SelectOption

Displays an <option>.

SuccessScreen

A wrapper around the success page.

LocalePicker

Displays a dropdown of locales for the user to choose.

RequiredFieldLabel

For displaying a message on the first page of the form explaining that "*" means a required field.

Hint

Displays a hint per-field that is associated via aria-describedby.

Fieldset

The HTML <fieldset> and <legend> component for wrapping related elements.

See fieldset documentation on MDN.

AnswerSummary

Displays a summary list of what the user has typed, typically used on the last page of a form before submission.