Forms

React forms are powered by a custom hook called useForm.

The useForm hook returns a pair of values: a state object containing the current state of the form and a submit function that performs the actual form submission.

const [state, submit] = useForm({
  site: '<your-site-id>',
  form: '<your-form-key>'
});

Here's a form component built with StaticKit:

import { useForm } from '@statickit/react';

function MyForm() {
  // Call the `useForm` hook in your function component
  const [state, submit] = useForm({
    site: '<your-site-id>',
    form: '<your-form-key>'
  });

  // Display success message in place of the form
  if (state.succeeded) {
    return (
      <div>Thank you for signing up!</div>
    )
  }

  return (
    <form onSubmit={submit}>
      <label htmlFor="email">Email</label>
      <input id="email" type="email" name="email" />
      <button type="submit">Sign up</button>
    </form>
  )
}

At a minimum, all you have to do is use a <form> element and pass submit as the onSubmit handler. Try it out!

State

The state object contains the following properties:

errors

Items in the errors array have the following properties:

Lifecycle

The properties in the state object change in the following ways:

• When the user submits the form, submitting becomes true
• If the submission fails server-side validations, errors is populated with the specific errors
• If the submission succeeds, succeeded becomes true
• After the request completes, submitting becomes false

Handling errors

Here's a more advanced example that displays validation errors for the email field:

- import { useForm } from '@statickit/react';
+ import { ValidationError, useForm } from '@statickit/react';

  function MyForm() {
    const [state, submit] = useForm('XXXXXXXXX');

    if (state.succeeded) {
      return (
        <div>Thank you for signing up!</div>
      )
    }

+   // Render email validation errors and disable the submit button when submitting
    return (
      <form onSubmit={submit}>
        <label htmlFor="email">Email</label>
        <input type="email" name="email" required />
+       <ValidationError field="email" prefix="Email" errors={state.errors} />
        <button type="submit" disabled={state.submitting}>Sign up</button>
      </form>
    )
  }

The ValidationError component accepts the following special properties:

• field — the name of the field for which to display errors (required)
• errors — the object containing validation errors (required)
• prefix — the human-friendly name of the field (optional, defaults to This field)

If the specified field has a validation error, this component renders a <div> containing the error message:

<div>
  {prefix} {message}
</div>

If the field does not have an error, nothing is rendered.

All other props set on ValidationError (such as className) are passed through to the <div> wrapper.

Configuration

At a minimum, you must set the site and form properties:

const [state, submit] = useForm({
  site: '<your-site-id>',   // found under the Settings tab
  form: '<your-form-key>'   // the key used in statickit.json
});

The useForm hook accepts the following properties:

form

The form property corresponds to the key used in your statickit.json file:

  // statickit.json
  {
    "forms": {
+     "newsletter": {
+       "name": "Newsletter Opt-In"
+     }
    }
  }

  // In your component
  const [state, submit] = useForm({
    site: '<your-site-id>',
+   form: 'newsletter'
  });

data

An Object containing Strings or Functions to merge with your form data.

Usage Example

  const [state, submit] = useForm({
    site: '<your-site-id>',
    form: '<your-form-key>',
+   data: {
+     _subject: 'Someone joined the newsletter',
+     pageTitle: function() {
+       // This function will be evaluated at submission time
+       return document.title;
+     }
+   }
});