Forms

HTML forms are powered by a little snippet of JavaScript.

<form id="my-form">
  <!-- Include any fields you need -->
  <label for="email">Email</label>
  <input id="email" type="email" name="email" value="" required />
  <button type="submit">Submit</button>
</form>

<script>
  window.sk=window.sk||function(){(sk.q=sk.q||[]).push(arguments)};

  sk('form', 'init', {
    site: '<your-site-id>',   // found under the Settings tab
    form: '<your-form-key>',  // the key used in statickit.json
    element: '#my-form'
  });
</script>

<!-- Put this anywhere on your page -->
<script defer src="https://js.statickit.com/statickit.js"></script>

Notice there is no action attribute on the form. Under the covers, we listen for the submit event and post to our servers in the background. This makes your form less vulnerable to spam because there is no URL exposed in the markup.

Try it out!

Post-submit behavior

By default, we replace the <form> element with a plain thank you message:

<div>Thank you!</div>

You customize this by implementing your own onSuccess callback. For example:

sk('form', 'init', {
  onSuccess: function(config) {
    var h = config.h;
    var form = config.form;
    var replacement = h('div.success-message', 'Thank you for joining!');
    form.parentNode.replaceChild(replacement, form);
  },
  // ...
});

Let's step through what's happening here:

• config.h is a simple helper for constructing DOM nodes called HyperScript
• config.form is a reference to the <form> element
• replacement is a new <div> with a success-message class
• The last line replaces the form with the replacement element

If you want to redirect to a different page instead, you can do that like this:

sk('form', 'init', {
  onSuccess: function(config) {
    window.location.href = '/thank-you';
  },
  // ...
});

Handling errors

When a server-side validation error occurs, the library will look for a matching data-sk-error attribute and populate the inner text with validation errors for the corresponding field:

<form id="my-form">
  <!-- ... -->
  <div data-sk-error="email" class="error-message"></div>
  <!-- ... -->
</form>

Email notifications

If you have email notifications configured for your form, you can customize the subject line and reply-to address using special fields:

• _subject
• _replyto or email

You can either add <input> fields to your form (to make these settable by the user) or set them programmatically.

sk('form', 'init', {
  data: {
    _subject: 'New contact submission'
  },
  // ...
});

Properties

At a minimum, you must set the site, form and element properties:

sk('form', 'init', {
  site: '<your-site-id>',   // found under the Settings tab
  form: '<your-form-key>',  // the key used in statickit.json
  element: '#my-form'       // the DOM selector for your <form> element
})

Here are all the available configuration properties:

form

The form property corresponds to the key used in your statickit.json file:

// statickit.json
{
  "forms": {
    "newsletter": {
      "name": "Newsletter Opt-In"
    }
  }
}

// JavaScript on page
sk('form', 'init', {
  site: '<your-site-id>',
  form: 'newsletter',
  element: '#my-form'
});

data

To set fields programmatically, use the data object:

sk('form', 'init', {
  data: {
    userAgent: navigator.userAgent
  },
  // ...
});

Values can either be static or functions (that will be evaluated at submission time):

sk('form', 'init', {
  data: {
    pageTitle: function() {
      return document.title;
    }
  },
  // ...
});

fields

The fields object allows you set optional metadata about your fields.

fields[key].prettyName

With the following configuration, validation messages will start with Email address instead of This field:

sk('form', 'init', {
  fields: {
    email: {
      prettyName: "Email address"
    }
  },
  // ...
});

fields[key].errorMessages

The following will display the custom messages instead of the defaults:

sk('form', 'init', {
  fields: {
    email: {
      prettyName: "Email address",
      errorMessages: {
        required: "Oops! You must provide an email address",
        emailFormat: "Hmm...this doesn't look like a real address"
      }
    }
  },
  // ...
});

The following server-side validation types are currently available:

renderErrors

The renderErrors function is responsible for clearing error messages for fields that don't have an errors and rendering messages for ones that do have errors.

sk('form', 'init', {
  renderErrors: function(config, errors) {
    // your own implementation
  },
  // ...
});

The default implementation looks for child elements with the data-sk-error={field} attribute and populates the innerHTML with the field's error message (or clears the innerHTML if there is no error).

Callbacks

You can optionally hook into various points of the form lifecycle using callbacks.

For example, suppose you want to track an analytics event every time a form is submitted successfully. It might look something like this:

sk('form', 'init', {
  onSuccess: function(config, resp) {
    analytics.track('Form submitted', { 
      email: resp.data.email 
    });

    window.location.href = '/success';
  },
  // ...
})

Here are all the available callbacks:

Response Object

The response object received by the onSuccess callback looks like this: