Forms

Forms are a simple way to gather submissions from your front-end and perform follow-up actions. For example, you can use forms build opt-in forms for Mailchimp or contact forms that email you when submitted.

How It Works

Suppose you have an opt-in form configured in your statickit.json file:

{
  "forms": {
    "optInForm": {
      "name": "Opt-In Form",
      "actions": [{ "app": "mailchimp", "type": "addOrUpdateContact" }]
    }
  }
}

You can use one of our JavaScript libraries for attaching the form to your interface. Here's what a form component looks like in React:

import { useForm } from '@statickit/react';
function OptInForm() {
  const [state, handleSubmit] = useForm('optInForm');
  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>
  )
}

Configuration

Forms accept the following config parameters:

PropertyTypeDefaultDescription
name *StringThe name of the form
actionsArray[]An Array of actions to perform after submission
fieldsObject{}Optional metadata about form fields
allowExtraFieldsBooleantrueWhether to accept fields not defined under fields

Example

Here's an example statickit.json file:

{
  "forms": {
    "contact": {
      "name": "Contact Form",
      "fields": {
        "email": { "type": "email", "required": true },
        "message": { "type": "text", "required": true }
      },
      "actions": [
        { "type": "email", "to": "john@example.com" }
      ],
      "allowExtraFields": false
    }
  }
}

Post-Submit Actions

Forms accept an array of actions to perform after submission. We have a few built-in actions:

TypeDescription
emailSends a notification email
webhookSends a webhook (HTTP POST) to a given url

We also have integrations with other apps:

AppDescription
mailchimpCreate subscribers and track events in Mailchimp
convertkitCreate subscribers and apply tags in ConvertKit

Send a notification email

Email a simple plain-text notification to somebody when the form is submitted.

KeyTypeDescription
to *StringThe email address of the recipient

Example

{
  "forms": {
    "contact": {
      "name": "Contact Form",
      "actions": [
        {
          "type": "email",
          "to": "john@example.com"
        }
      ]
    }
  }
}

Send a webhook

Send an HTTP POST to a given URL with a JSON body.

KeyTypeDescription
url *StringThe endpoint to send the POST request

Example

{
  "forms": {
    "contact": {
      "name": "Contact Form",
      "actions": [
        {
          "type": "webhook",
          "url": "http://example.com/hook"
        }
      ]
    }
  }
}

Request Body

The body of the webhook contains the following properties in JSON format:

KeyTypeDescription
form_idStringThe form ID
submission_idStringThe form submission ID
occurred_atStringThe submission timestamp (in ISO-8601 format)
dataObjectThe submission fields

Here's an example:

{
  "type": "form.submitted",
  "form_id": "6f711462a450",
  "submission_id": "ef3f189d-c83d-4210-8320-03b4ee27394d",
  "occurred_at": "2020-01-01T00:00:00Z",
  "data": {
    "first_name": "Bob",
    "last_name": "Loblaw"
  }
}

Field Rules

You can optionally configure which fields are allowed, the type they should be, and various validation rules for them.

Note: By default, StaticKit will accept any fields you pass in from the client-side. However, defining your fields here allows you to add validations (such as marking a field as required) and give them human-friendly names.

Field objects can contain the following properties:

KeyTypeDescription
typeStringThe field type (text, email)
prettyNameStringThe human-friendly name of the field
requiredBooleanSpecifies whether the field is required

Example

{
  "forms": {
    "contact": {
      "name": "Contact Form",
      "fields": {
        "email": {
          "type": "email",
          "prettyName": "Email address",
          "required": true
        }
      }
    }
  }
}