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.

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": "[email protected]" }
      ],
      "allowExtraFields": false
    }
  }
}

Actions

An Array of actions to perform after the form is submitted. 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": "[email protected]"
        }
      ]
    }
  }
}

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

Fields

An Object containing optional field metadata.

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
        }
      }
    }
  }
}