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:
Property | Type | Default | Description |
---|---|---|---|
name * | String | The name of the form | |
actions | Array | [] | An Array of actions to perform after submission |
fields | Object | {} | Optional metadata about form fields |
allowExtraFields | Boolean | true | Whether 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:
Type | Description |
---|---|
email | Sends a notification email |
webhook | Sends a webhook (HTTP POST) to a given url |
We also have integrations with other apps:
App | Description |
---|---|
mailchimp | Create subscribers and track events in Mailchimp |
convertkit | Create subscribers and apply tags in ConvertKit |
Send a notification email
Email a simple plain-text notification to somebody when the form is submitted.
Key | Type | Description |
---|---|---|
to * | String | The 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.
Key | Type | Description |
---|---|---|
url * | String | The 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:
Key | Type | Description |
---|---|---|
form_id | String | The form ID |
submission_id | String | The form submission ID |
occurred_at | String | The submission timestamp (in ISO-8601 format) |
data | Object | The 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:
Key | Type | Description |
---|---|---|
type | String | The field type (text, email) |
prettyName | String | The human-friendly name of the field |
required | Boolean | Specifies whether the field is required |
Example
{"forms": {"contact": {"name": "Contact Form","fields": {"email": {"type": "email","prettyName": "Email address","required": true}}}}}