Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/formsmd/formsmd/llms.txt

Use this file to discover all available pages before exploring further.

​
Quickstart

This guide will walk you through creating a complete multi-step onboarding form with conditional logic in just a few minutes.

​
What we’ll build

We’ll create a user onboarding form that:
  • Collects the user’s position
  • Shows a follow-up field if they select “Other”
  • Asks how they heard about us
  • Conditionally asks for a referrer email if they were recommended

​
Step 1: Set up your project

First, install Forms.md and set up your HTML:
1

Install Forms.md

npm install formsmd
2

Create your HTML container

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Onboarding Form</title>
</head>
<body>
  <div id="onboarding-form-container"></div>
  <script src="app.js"></script>
</body>
</html>

​
Step 2: Build the form with Composer

The Composer class provides methods to build your form programmatically: 
import "formsmd/dist/css/formsmd.min.css";
import { Composer, Formsmd } from "formsmd";

// Create form with ID and submission endpoint
const composer = new Composer({
  id: "onboarding-form",
  postUrl: "/api/onboard"
});

// Add a choice input for position
composer.choiceInput("position", {
  question: "What's your position?",
  choices: ["Product Manager", "Software Engineer", "Founder", "Other"],
  required: true
});

// Conditional text input - only shows if "Other" is selected
composer.textInput("positionOther", {
  question: "Other",
  required: true,
  labelStyle: "classic",
  displayCondition: {
    dependencies: ["position"],
    condition: "position == 'Other'"
  }
});

// Start a new slide with progress at 50%
composer.slide({
  pageProgress: "50%"
});

// Ask how they heard about us
composer.choiceInput("referralSource", {
  question: "How did you hear about us?",
  choices: ["News", "Search Engine", "Social Media", "Recommendation"],
  required: true
});

// Conditional slide - only shows if referred by someone
composer.slide({
  jumpCondition: "referralSource == 'Recommendation'",
  pageProgress: "75%"
});

// Conditional email input for recommender
composer.emailInput("recommender", {
  question: "Who recommended you?",
  description: "We may be able to reach out to them and provide a discount for helping us out."
});

​
Step 3: Initialize and render the form

Use the Formsmd class to initialize the form with your template: 
const formsmd = new Formsmd(
  composer.template,
  document.getElementById("onboarding-form-container"),
  {
    postHeaders: {
      Authorization: `Bearer ${localStorage.getItem("token")}`
    }
  }
);

formsmd.init();
The composer.template property contains the generated form template that gets passed to Formsmd for rendering.

​
Complete example

Here’s the full code in one place: 
import "formsmd/dist/css/formsmd.min.css";
import { Composer, Formsmd } from "formsmd";

// Create form with ID and submission endpoint
const composer = new Composer({
  id: "onboarding-form",
  postUrl: "/api/onboard"
});

// Choice input for position
composer.choiceInput("position", {
  question: "What's your position?",
  choices: ["Product Manager", "Software Engineer", "Founder", "Other"],
  required: true
});

// Text input if user selects "Other" position
composer.textInput("positionOther", {
  question: "Other",
  required: true,
  labelStyle: "classic",
  displayCondition: {
    dependencies: ["position"],
    condition: "position == 'Other'"
  }
});

// Start new slide, progress indicator at 50%
composer.slide({
  pageProgress: "50%"
});

// Choice input for how user discovered the product
composer.choiceInput("referralSource", {
  question: "How did you hear about us?",
  choices: ["News", "Search Engine", "Social Media", "Recommendation"],
  required: true
});

// Start new slide, show only if user was recommended, progress indicator at 75%
composer.slide({
  jumpCondition: "referralSource == 'Recommendation'",
  pageProgress: "75%"
});

// Email input for recommender email address
composer.emailInput("recommender", {
  question: "Who recommended you?",
  description: "We may be able to reach out to them and provide a discount for helping us out."
});

// Initialize with template, container, and options
const formsmd = new Formsmd(
  composer.template,
  document.getElementById("onboarding-form-container"),
  {
    postHeaders: {
      Authorization: `Bearer ${localStorage.getItem("token")}`
    }
  }
);
formsmd.init();

​
Understanding the code

​
Composer class

The Composer class is used to build forms programmatically:
src/composer.js:164-191
const composer = new Composer({
  id: "onboarding-form",
  postUrl: "/api/onboard"
});
Composer provides methods for each form field type:
  • textInput() - Single or multi-line text
  • emailInput() - Email with validation
  • choiceInput() - Radio buttons or checkboxes
  • numberInput() - Numeric input with min/max
  • selectBox() - Dropdown select
  • ratingInput() - Star or heart ratings
  • opinionScale() - 0-10 scale inputs
  • dateInput(), timeInput(), datetimeInput() - Date/time pickers
  • fileInput() - File uploads
  • And more!

​
Conditional logic

Use displayCondition to show/hide fields based on other values: 
displayCondition: {
  dependencies: ["position"],  // Fields to watch
  condition: "position == 'Other'"  // JavaScript expression
}

​
Slides and navigation

Create multi-step forms by adding slides: 
composer.slide({
  jumpCondition: "referralSource == 'Recommendation'",  // Only show if condition is true
  pageProgress: "75%"  // Show progress indicator
});

​
Formsmd class

The Formsmd class initializes and renders the form:
src/main.js:125-127
const formsmd = new Formsmd(
  composer.template,  // Generated template string
  document.getElementById("container"),  // DOM container
  { postHeaders: { /* ... */ } }  // Options
);
formsmd.init();

​
Handling form submissions

By default, Forms.md will POST the form data to the URL specified in postUrl. The data is sent as JSON: 
{
  "position": "Software Engineer",
  "referralSource": "Recommendation",
  "recommender": "jane@example.com"
}
Fields that aren’t shown due to conditional logic won’t be included in the submission.

​
Custom submission headers

Pass custom headers via the postHeaders option: 
const formsmd = new Formsmd(composer.template, container, {
  postHeaders: {
    "Authorization": "Bearer token",
    "X-Custom-Header": "value"
  }
});

​
Include additional data

Add extra fields to every submission with postData: 
const formsmd = new Formsmd(composer.template, container, {
  postData: {
    userId: "12345",
    timestamp: Date.now()
  }
});

​
Next steps

Now that you’ve built your first form, explore more advanced features:

Form inputs

Explore all available field types and their options

Theming

Customize colors, fonts, and layouts

Conditional logic

Add display conditions and slide jumps

Localization

Support multiple languages