React

Versions: 1.x | 2.x

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/react

Source on GitHub | npm package

The hooks in this library expect you to place the <StaticKitProvider> in your top-level app or layout component. Here's an example of a custom Next.js _app.js file:

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

function App({ Component, pageProps }) {
  return (
    <StaticKitProvider site="{your-site-id}">
      <Component {...pageProps} />
    </StaticKitProvider>
  );
}

export default App;

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('<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" disabled={state.submitting}>Sign up</button>
    </form>
  )
}

State object

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

const [state, handleSubmit] = useForm('<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 [])

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")
propertiesAn object containing various additional properties about the error

State changes over time in the following ways:

  • When handleSubmit is called, 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 submission request finishes, submitting always becomes false

Validations

Here's an example form using the ValidationError component to display field errors:

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

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

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

  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")

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

If the given field is invalid, this component renders a <div> containing the error message:

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

Options

This hook accepts two arguments: the form key and an object containing options.

const [state, handleSubmit] = useForm('<your-form-key>', options);

Here are the acceptable options:

KeyTypeDescription
dataobjectAn object containing additional form fields to send
clientStaticKitAn instance of the StaticKit client
debugbooleanLog debug statements for troubleshooting

data

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

Usage Example

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