React

Versions: 1.x | 2.x

You are viewing the documentation for the 1.0 version of this library. We recommend upgrading the 2.0 version.

Installation

This library assumes that React is already installed in your environment as a peer dependency. Our helpers rely on React Hooks, so you must be on version 16.8.0 or higher.

npm install @statickit/[email protected]^1.0

Source on GitHub | npm package

Usage

The useForm React hook is the easiest way to setup a React form with StaticKit.

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

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

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

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

State object

The first value in the array returned by this hook is a state object:

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

The state object contains the following properties:

KeyDescription
submittingA Boolean indicating whether the form is currently submitting (defaults to false)
succeededA Boolean indicating whether the form successfully submitted (defaults to false)
errorsAn Array of server-side validation errors (defaults to [])

errors

Items in the errors array have the following properties:

KeyDescription
fieldThe name of the field
messageA human-readable error message fragment (e.g. "is required")
codeA machine-friendly error code (e.g. "REQUIRED" or "EMAIL_FORMAT")

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, handleSubmit] = 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={handleSubmit}>
        <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.

Options

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

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

The hook accepts the following properties:

KeyTypeDescription
site *StringThe site ID (found in your Settings tab)
form *StringThe form key
dataObjectAn object containing additional form fields to send

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;
+     }
+   }
});