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

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