Forminit + Jekyll Integration Guide

Jekyll is a static site generator that outputs plain HTML files with no server-side processing. Forminit handles all form submissions through our client-side SDK, making it a perfect match for Jekyll sites.

What you’ll get:

Accept form submissions without building a backend
Email notifications for new submissions
Spam protection (reCAPTCHA, hCaptcha, honeypot)
File uploads support
Submission dashboard to manage responses

Requirements:

A Jekyll site (any version)
A Forminit account and Form ID

Quick Start

Step 1: Create a Form on Forminit

Sign up or log in at forminit.com
Create a new form
Go to Form Settings → Set authentication mode to Public
Copy your Form ID (e.g., abc123xyz)

Step 2: Create a Form Include

Create a new include file for your contact form:

<!-- _includes/contact-form.html -->

<form id="contact-form">
  <div class="form-group">
    <label for="firstName">First Name</label>
    <input 
      type="text" 
      id="firstName" 
      name="fi-sender-firstName" 
      placeholder="John" 
      required 
    />
  </div>

  <div class="form-group">
    <label for="lastName">Last Name</label>
    <input 
      type="text" 
      id="lastName" 
      name="fi-sender-lastName" 
      placeholder="Doe" 
      required 
    />
  </div>

  <div class="form-group">
    <label for="email">Email</label>
    <input 
      type="email" 
      id="email" 
      name="fi-sender-email" 
      placeholder="john@example.com" 
      required 
    />
  </div>

  <div class="form-group">
    <label for="message">Message</label>
    <textarea 
      id="message" 
      name="fi-text-message" 
      placeholder="Your message..." 
      rows="5" 
      required
    ></textarea>
  </div>

  <button type="submit">Send Message</button>
</form>

<p id="form-status"></p>

Step 3: Add the Forminit SDK

Create an include for the form script:

<!-- _includes/forminit-script.html -->

<script src="https://forminit.com/sdk/v1/forminit.js"></script>

<script>
  const forminit = new Forminit();
  const FORM_ID = '{{ site.forminit_form_id | default: "YOUR_FORM_ID" }}';

  const form = document.getElementById('contact-form');
  const status = document.getElementById('form-status');

  form.addEventListener('submit', async function(event) {
    event.preventDefault();
    
    // Show loading state
    status.textContent = 'Sending...';
    status.className = 'status-loading';

    const formData = new FormData(form);
    const { data, error } = await forminit.submit(FORM_ID, formData);

    if (error) {
      status.textContent = error.message;
      status.className = 'status-error';
      return;
    }

    // Success
    status.textContent = 'Message sent successfully!';
    status.className = 'status-success';
    form.reset();
  });
</script>

Step 4: Include in Your Layout

Add the form and script to your page layout:

<!-- _layouts/default.html -->

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{{ page.title }} | {{ site.title }}</title>
  <link rel="stylesheet" href="{{ '/assets/css/style.css' | relative_url }}">
</head>
<body>
  {% include header.html %}
  
  <main>
    {{ content }}
  </main>
  
  {% include footer.html %}
  
  <!-- Add Forminit script on pages that need it -->
  {% if page.has_form %}
    {% include forminit-script.html %}
  {% endif %}
</body>
</html>

Step 5: Create Your Contact Page

Create a contact page that uses the form:

---
layout: default
title: Contact
permalink: /contact/
has_form: true
---

<div class="contact-page">
  <h1>Contact Us</h1>
  <p>We'd love to hear from you. Fill out the form below and we'll get back to you soon.</p>
  
  {% include contact-form.html %}
</div>

Or using Markdown:

---
layout: default
title: Contact
permalink: /contact/
has_form: true
---

# Contact Us

We'd love to hear from you. Fill out the form below and we'll get back to you soon.

{% include contact-form.html %}

Using Site Configuration for Form ID

Store your Form ID in Jekyll’s _config.yml for easier management:

# _config.yml

title: My Site
description: My awesome Jekyll site

# Forminit configuration
forminit_form_id: "abc123xyz"

Then reference it in your script:

const FORM_ID = '{{ site.forminit_form_id }}';

Form Field Reference

For a complete list of available form blocks (text, email, phone, file, rating, select, etc.) and field naming patterns, see the Form Blocks documentation.

Complete Examples

Contact Form with Subject Selection

<!-- _includes/contact-form.html -->

<form id="contact-form">
  <input type="text" name="fi-sender-firstName" placeholder="First name" required />
  <input type="text" name="fi-sender-lastName" placeholder="Last name" required />
  <input type="email" name="fi-sender-email" placeholder="Email" required />
  
  <select name="fi-select-subject" required>
    <option value="">Select a subject</option>
    <option value="general">General Inquiry</option>
    <option value="support">Support</option>
    <option value="sales">Sales</option>
    <option value="partnership">Partnership</option>
  </select>
  
  <textarea name="fi-text-message" placeholder="Your message" required></textarea>
  
  <button type="submit">Send</button>
</form>

<p id="form-status"></p>

<!-- _includes/newsletter-form.html -->

<form id="newsletter-form">
  <input type="email" name="fi-sender-email" placeholder="Enter your email" required />
  <button type="submit">Subscribe</button>
</form>

<p id="newsletter-status"></p>

<script src="https://forminit.com/sdk/v1/forminit.js"></script>
<script>
  const forminit = new Forminit();
  const FORM_ID = '{{ site.newsletter_form_id }}';

  const form = document.getElementById('newsletter-form');
  const status = document.getElementById('newsletter-status');

  form.addEventListener('submit', async function(event) {
    event.preventDefault();
    status.textContent = 'Subscribing...';

    const formData = new FormData(form);
    const { data, error } = await forminit.submit(FORM_ID, formData);

    if (error) {
      status.textContent = error.message;
      return;
    }

    status.textContent = 'Thank you for subscribing!';
    form.reset();
  });
</script>

Feedback Form with Rating

<!-- _includes/feedback-form.html -->

<form id="feedback-form">
  <input type="email" name="fi-sender-email" placeholder="Email (optional)" />
  
  <fieldset>
    <legend>How would you rate your experience?</legend>
    <label><input type="radio" name="fi-rating-experience" value="1" /> 1</label>
    <label><input type="radio" name="fi-rating-experience" value="2" /> 2</label>
    <label><input type="radio" name="fi-rating-experience" value="3" /> 3</label>
    <label><input type="radio" name="fi-rating-experience" value="4" /> 4</label>
    <label><input type="radio" name="fi-rating-experience" value="5" /> 5</label>
  </fieldset>
  
  <textarea name="fi-text-feedback" placeholder="Tell us more (optional)"></textarea>
  
  <button type="submit">Submit Feedback</button>
</form>

<p id="feedback-status"></p>

Job Application with File Upload

<!-- _includes/application-form.html -->

<form id="application-form">
  <input type="text" name="fi-sender-firstName" placeholder="First name" required />
  <input type="text" name="fi-sender-lastName" placeholder="Last name" required />
  <input type="email" name="fi-sender-email" placeholder="Email" required />
  <input type="tel" name="fi-sender-phone" placeholder="Phone (+1234567890)" />
  
  <input type="url" name="fi-url-linkedin" placeholder="LinkedIn profile URL" />
  <input type="url" name="fi-url-portfolio" placeholder="Portfolio URL" />
  
  <select name="fi-select-position" required>
    <option value="">Select position</option>
    <option value="frontend">Frontend Developer</option>
    <option value="backend">Backend Developer</option>
    <option value="fullstack">Full Stack Developer</option>
    <option value="designer">UI/UX Designer</option>
  </select>
  
  <label>
    Resume (PDF)
    <input type="file" name="fi-file-resume" accept=".pdf" required />
  </label>
  
  <label>
    Cover Letter (optional)
    <input type="file" name="fi-file-cover-letter" accept=".pdf,.doc,.docx" />
  </label>
  
  <textarea name="fi-text-why-join" placeholder="Why do you want to join us?"></textarea>
  
  <button type="submit">Submit Application</button>
</form>

<p id="application-status"></p>

Multiple Forms on One Site

If you have multiple forms (contact, newsletter, application), store different Form IDs in your config:

# _config.yml

title: My Site

# Forminit Form IDs
forminit:
  contact: "abc123"
  newsletter: "xyz456"
  application: "sms55"

Then reference them in your templates:

const FORM_ID = '{{ site.forminit.contact }}';

Using Data Files for Form Configuration

For more complex configurations, use Jekyll’s data files:

# _data/forms.yml

contact:
  id: "abc123"
  success_message: "Thanks for reaching out!"
  
newsletter:
  id: "xyz456"
  success_message: "You're subscribed!"
  
application:
  id: "sms55"
  success_message: "Application received!"

Access in your templates:

const FORM_ID = '{{ site.data.forms.contact.id }}';
const SUCCESS_MESSAGE = '{{ site.data.forms.contact.success_message }}';

Handling Form Submission Response

The SDK returns { data, redirectUrl, error }:

On success:

{
  data: {
    hashId: "7LMIBoYY74JOCp1k",      // Unique submission ID
    date: "2026-01-01 21:10:24",      // Timestamp
    blocks: {                          // Submitted values
      sender: {
        firstName: "John",
        lastName: "Doe",
        email: "john@example.com"
      },
      message: "Hello from Jekyll!"
    }
  },
  redirectUrl: "https://forminit.com/thank-you"
}

On error:

{
  error: {
    error: "ERROR_CODE",
    code: 400,
    message: "Human-readable error message"
  }
}

Redirect After Submission

If you prefer to redirect users to a thank-you page:

form.addEventListener('submit', async function(event) {
  event.preventDefault();

  const formData = new FormData(form);
  const { data, redirectUrl, error } = await forminit.submit(FORM_ID, formData);

  if (error) {
    status.textContent = error.message;
    return;
  }

  // Redirect to thank-you page
  window.location.href = '/thank-you/';
  // Or use Forminit's redirect URL:
  // window.location.href = redirectUrl;
});

Create a thank-you page:

---
layout: default
title: Thank You
permalink: /thank-you/
---

# Thank You!

Thank you for your message! We'll get back to you soon.

[← Back to Home](/)

Project Structure Example

Here’s a typical Jekyll project structure with Forminit forms:

my-jekyll-site/
├── _config.yml                # Site config with Form IDs
├── _data/
│   └── forms.yml              # Optional: form configurations
├── _includes/
│   ├── contact-form.html      # Form HTML
│   ├── forminit-script.html   # Form submission script
│   ├── header.html
│   └── footer.html
├── _layouts/
│   └── default.html           # Base layout
├── _posts/                    # Blog posts
├── assets/
│   └── css/
│       └── forms.css          # Form styles
├── contact.md                 # Contact page
├── thank-you.md               # Thank you page
└── index.md                   # Homepage

GitHub Pages Deployment

Jekyll works seamlessly with GitHub Pages. Your Forminit forms will work without any additional configuration since everything runs client-side.

# _config.yml for GitHub Pages

title: My Site
url: "https://yourusername.github.io"
baseurl: "/your-repo-name"

forminit_form_id: "abc123xyz"

Next Steps

View your submissions in the Forminit dashboard
Set up email notifications for new submissions
Explore webhook integrations for advanced workflows