<CustomField>

Start of documentation content

Allows custom field extensions to Formally forms in JSX

This documentation page is about Custom Fields in JSX specifically. To read more generally about Custom Fields in Formally.

When using React JSX you may implement a Custom Field resolver as...

Use of <CustomField>

<CustomField
  id="myCustomField"
  name="map-picker"
  labelHtml={{ en: 'your custom component label' }}
  component="myCustomField"
/>

Provide a resolver for myCustomField with the customFields prop,

<Formally customFields={{ myCustomField: myComponent }} />
const myComponent = ({
  inputFieldId,
  locale,
  node,
  name,
  value,
  fieldState,
  label,
  hint,
  error,
  onChange,
  onBlur,
}) => {
  // your custom component goes here and
  // it can be anything you want.
  //
  // Use the 'value' prop, and 'onChange' to
  // update the value in Formally. Use 'onBlur'
  // to trigger validation checks.
  //
  // For accessibility reasons be sure to use
  // the 'label' prop or (render your own label
  // using htmlFor=inputFieldId )

  return (
    <>
      {label}
      <input
        id={inputFieldId}
        value={value}
        onChange={(e) => onChange(e.target.value)}
        onBlur={onBlur}
      />
    </>
  );
};

<CustomField>'s props

PropAboutType
component

A reference to React component function to render the custom field.

The value can either be

1) a string (the 'Custom Id' in the Form Builder) which is resolved against the the <Formally customFields={ {'myCustomId': customReactComponent} } /> The customReactComponent must be a React component adhering to (2) 2) A React component that receives the following props: * Props:

* `inputFieldId` (string): globally unique id that can be used for HTML references `<label for={inputFieldId}>` and `<input id={inputFieldId}>`.
* `locale` (string): the user's current locale. Select localised strings (eg. from `node`) based on this.
* `node`: a reference to node props.
* `name` (string): for use in the 'name' attribute.
* `value` (any): the current value (any type).
* `fieldState` (object): React Hook Form ControllerFieldState object.
* `label`: React component to render a label. Use it like {label}.
* `hint`: React component to render a hint. Use it like {hint}.
* `error`: React component to render an error. Use it like {error}.
* `onChange` (function): set the updated value to Formally (any type).
* `onBlur` (function): trigger validation checks, typically when bluring (leaving) a field.
string | React.FC<CustomFieldProps>
hintHtml

Localisable HTML: hint content

E.g.

{
  en: '<p>Welcome to my form</p>',
}
LocalisedHtml
isRequired

Whether users are required to fill in this form field.

The custom component should use this to affect aria-required and whether a * is displayed next to the form field, etc.

boolean
labelHtml

Localisable HTML: Label content

E.g.

{
  en: '<p>Welcome to my form</p>',
}
LocalisedHtml
name

The name attribute in HTML (MDN name attribute)

Name of the form control.

Submitted with the form as part of a name:value pair in the <Formally onSubmit> callback prop valuesAsFormNames.

string
validationErrorInvalidHtml

Localisable HTML: invalid validation content

LocalisedHtml
validationErrorRequiredHtml

Localisable HTML: required validation content

LocalisedHtml
id

Component Id.

Must be unique within the form.

string
meta

Arbitrary metadata on this node.

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

MetaData
hasChildrenById

Non-editable.

Used to indicate that this component doesn't have children.

false
hasTagsById

Non-editable.

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

false
isFormField

Non-editable.

Used to indicate that this component is a form field.

true
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 "DateInput".

"CustomField"