Skip to content

React ​

bash
npm install @canardform/sdk@alpha

The form builds itself ​

tsx
import { CanardForm } from '@canardform/sdk/react';

<CanardForm
  formId="ID"
  classes={{ form: 'contact', submit: 'btn' }}
  onSubmitted={(id) => track(id)}
/>;

Like mountForm, but as a native component: fields, labels, languages, display conditions, bot protection, per-field errors and the thank-you message come from the published form. Server-side rendering included (Next.js): pass definition read with getForm to show the fields from the first render. See Server-side rendering.

PropDescription
formIdThe form id
classesform, field, error, success, closed, unavailable, submit
renderField({ field, error, children }) => ReactNode, see below
onSubmitted(submissionId) => void; without it, the thank-you message is shown
loadingShown while the fields load
messagessubmit, success, closed, unavailable, next, previous; see Built-in texts
definitionThe form read on the server with getForm
lang, publicUrl, idempotencyKey, fetchSame as submitForm

Taking control of the HTML ​

Three levels:

  1. Classes: classes (form, field, error, success, closed, unavailable, submit), without touching the markup.
  2. One field: renderField={({ field, error, children }) => …}. Return children to keep the default rendering; <FieldInput field={field} error={error} /> gives the control alone (marked invalid and pointing to cf-<key>-error when there is an error: give that id to your message). The loading prop sets what shows while loading.
  3. All the HTML: the useCanardForm hook below, with your own fields.

Your fields, the SDK does the rest ​

tsx
import { useCanardForm } from '@canardform/sdk/react';

export default function Contact() {
  const form = useCanardForm('ID');
  if (form.status === 'sent') return <p>Thank you!</p>;

  return (
    <form onSubmit={form.handleSubmit} onChange={form.handleChange}>
      <input type="email" name="email" required />
      {form.isVisible('budget') && <input type="number" name="budget" />}
      {form.errors.email && <p>{form.errors.email}</p>}
      <div ref={form.captchaRef} />
      <button disabled={form.status === 'sending'}>Send</button>
    </form>
  );
}

The hook returns:

NameDescription
statusidle, sending, sent or error
errorsFirst error of each refused field, by key: errors.email
errorGeneral message (closed form, network…)
submissionIdId of the submission once sent
definitionThe published form, null until loaded
unavailabletrue when the form could not be loaded (unknown form, server unreachable)
isVisible(key)Display conditions
handleSubmitFor onSubmit of the <form>
handleChangeFor onChange of the <form>, updates the conditions
submit(data)Sends a FormData or an object, resolves to the id or null
reset()Back to the initial state
captchaRefRef for an empty element of the form, see Bot protection
captchaErrorMessage when the bot check was not done, to show next to it
steps, step, isStep(key), next(element), previous()See Steps and conditions
showField(key)Shows the step of this field (link of an error summary)

No rendering is imposed. With server-side rendering, nothing is read before mount; pass definition (read with getForm on the server) to know the conditions from the first render.

Released under the MIT License.