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:

Install Forms.md

npm install formsmd

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
}

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

Get Started

Core Concepts

Guides

Examples

Quickstart

Quickstart

What we’ll build

Step 1: Set up your project

Step 2: Build the form with Composer

Step 3: Initialize and render the form

Complete example

Understanding the code

Composer class

Conditional logic

Slides and navigation

Formsmd class

Handling form submissions

Custom submission headers

Include additional data

Next steps

Form inputs

Theming

Conditional logic

Localization

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Examples

Documentation Index

​Quickstart

​What we’ll build

​Step 1: Set up your project

​Step 2: Build the form with Composer

​Step 3: Initialize and render the form

​Complete example

​Understanding the code

​Composer class

​Conditional logic

​Slides and navigation

​Formsmd class

​Handling form submissions

​Custom submission headers

​Include additional data

​Next steps

Form inputs

Theming

Conditional logic

Localization

Build docs developers (and LLMs) love

Quickstart

What we’ll build

Step 1: Set up your project

Step 2: Build the form with Composer

Step 3: Initialize and render the form

Complete example

Understanding the code

Composer class

Conditional logic

Slides and navigation

Formsmd class

Handling form submissions

Custom submission headers

Include additional data

Next steps