Installation and usage

Install and start building powerful multi-step forms and surveys.

Forms.md (formerly Blocks.md) lets you build powerful multi-step forms and surveys with minimal code. Create production-ready forms that are privacy-focused, accessible, localizable, and themeable. Perfect for user onboarding, data collection, customer feedback, and much more.

---

Installation

Install via npm

npm install formsmd

Use in browser

Download the distribution files from the GitHub repo. Include the files using <link> and <script> tags in your template.

<!-- Forms.md CSS -->
<link rel="stylesheet" type="text/css" href="path/to/formsmd/dist/css/formsmd.min.css" />
<!--
Or RTL version:
<link rel="stylesheet" type="text/css" href="path/to/formsmd/dist/css/formsmd.rtl.min.css" />
-->

<!-- Forms.md JS bundle -->
<script src="path/to/formsmd/dist/js/formsmd.bundle.min.js"></script>

<!--
Use Composer in the browser:
<script src="path/to/formsmd/dist/js/composer.bundle.min.js"></script>
-->

---

Usage

Create forms programmatically using the Composer class, then initialize them with the Formsmd class by passing in the template.

With composer

import "formsmd/dist/css/formsmd.min.css"; // Or import formsmd.rtl.min.css in case of RTL
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();

Markdown-like

import "formsmd/dist/css/formsmd.min.css"; // Or import formsmd.rtl.min.css in case of RTL
import { Formsmd } from "formsmd";
 
// Create template
const template = `
#! id = onboarding-form
#! post-url = /api/onboard
 
position* = ChoiceInput(
  | question = What's your position?
  | choices = Product Manager, Software Engineer, Founder, Other
)
 
::: [{$ position $}]
{% if position == "Other" %}
positionOther* = TextInput(
  | question = Other
  | labelStyle = classic
)
{% endif %}
:::
 
---
|> 50%
 
referralSource* = ChoiceInput(
  | question = How did you hear about us?
  | choices = News, Search Engine, Social Media, Recommendation
)
 
---
-> referralSource == "Recommendation"
|> 75%
 
recommender = EmailInput(
  | 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(
  template,
  document.getElementById("onboarding-form-container"),
  {
    postHeaders: {
      Authorization: `Bearer ${localStorage.getItem("token")}`
    }
  }
);
formsmd.init();

Slide 1 when "Other" is picked

Slide 2

Slide 3 (only shown if the user was recommended)

---

Form settings

The Composer constructor accepts an object called settings as the argument. These are called form settings, and they can be used to configure various aspects of the form.

constructor(settings: object)

Example

const composer = new Composer({
  formStyle: "classic",
  id: "my-form",
  postUrl: "/api/endpoint",
});

Generates the following Markdown-like syntax:

#! form-style = classic
#! id = my-form
#! post-url = /api/endpoint

Arguments

Name	Type	Description
settings	object	Object containing configuration settings for the form.

Settings parameters

With composer

The formsmdBranding and/or footer parameters can only be set to "hide" if your site has a Pro subscription (or above).

The settings argument can contain the following parameters:

Name	Type	Description
autofocus	"all-slides"	If set to "all-slides", when a new slide becomes active (including first slide on page load), the first form field will be auto-focused.
buttonAlignment	"center" | "end" | "stretch"	Sets the alignment of the CTA buttons on each slide.
cssPrefix	string	Prefix added to all CSS classes. Default is "fmd-". If set to "none", the prefix is removed altogether.
dir	"ltr" | "rtl"	Direction of the form's text. Default is "ltr".
fieldSize	"sm"	If set to "sm", the size of form fields will be made smaller.
fontSize	"sm" | "lg"	Makes the font size of everything on the form smaller or larger.
formDelimiter	string	Used to separate parameters when creating form fields. Default is "|".
formsmdBranding	"hide" | "show"	Controls visibility of the Forms.md branding. Please note, you need a Pro subscription (or above) to hide the branding.
formStyle	"classic"	If set to "classic", the form fields will have a classic appearance.
footer	"hide" | "show"	Controls visibility of the footer. Please note, you need a Pro subscription (or above) to hide the footer.
header	"hide" | "show" | "align"	Controls header visibility and alignment.
headings	"anchored"	If set to "anchored", all headings will contain an anchor link.
id	string	Identifier for the form. It is highly recommended that every form is given a unique id.
labelStyle	"classic"	If set to "classic", the question and description of form fields will be made smaller.
localization	string	Sets the language for automatic translation. Default is "en".
page	"form-slides" | "slides" | "single"	Determines the layout of the form. Default is "form-slides".
pageProgress	"hide" | "show" | "decorative"	Controls visibility and function of the page progress.
placeholders	"hide" | "show"	Controls visibility of input placeholders.
postSheetName	string	When sending responses directly to Google Sheets, specifies which sheet to save responses to.
postUrl	string	URL to send form responses to using POST request.
restartButton	"show"	If set to "show", a restart button will be visible on the end slide.
rounded	"none" | "pill"	Controls rounding of buttons and UI elements.
slideControls	"hide" | "show"	Controls visibility of next and previous buttons.
slideDelimiter	string	Specifies where new slides are created. Default is "---".
submitButtonText	string	Custom text for all submit buttons.
verticalAlignment	"start"	If set to "start", content is aligned to the top of the container vertically.

Markdown-like

The formsmd-branding and/or footer parameters can only be set to hide if your site has a Pro subscription (or above).

A setting is a line in the format #! {name} = {value} added anywhere (but usually at the very start). For example, #! button-alignment = center. The following settings are available:

Name	Value	Description
autofocus	all-slides	If set to all-slides, when a new slide becomes active (including first slide on page load), the first form field will be auto-focused.
button-alignment	center | end | stretch	Sets the alignment of the CTA buttons on each slide.
css-prefix	string	Prefix added to all CSS classes. Default is fmd-. If set to none, the prefix is removed altogether.
dir	ltr | rtl	Direction of the form's text. Default is ltr.
field-size	sm	If set to sm, the size of form fields will be made smaller.
font-size	sm | lg	Makes the font size of everything on the form smaller or larger.
form-delimiter	string	Used to separate parameters when creating form fields. Default is |.
formsmd-branding	hide | show	Controls visibility of the Forms.md branding. Please note, you need a Pro subscription (or above) to hide the branding.
form-style	classic	If set to classic, the form fields will have a classic appearance.
footer	hide | show	Controls visibility of the footer. Please note, you need a Pro subscription (or above) to hide the footer.
header	hide | show | align	Controls header visibility and alignment.
headings	anchored	If set to anchored, all headings will contain an anchor link.
id	string	Identifier for the form. It is highly recommended that every form is given a unique id.
label-style	classic	If set to classic, the question and description of form fields will be made smaller.
localization	string	Sets the language for automatic translation. Default is "en".
page	form-slides | slides | single	Determines the layout of the form. Default is form-slides.
page-progress	hide | show | decorative	Controls visibility and function of the page progress.
placeholders	hide | show	Controls visibility of input placeholders.
post-sheet-name	string	When sending responses directly to Google Sheets, specifies which sheet to save responses to.
post-url	string	URL to send form responses to using POST request.
restart-button	show	If set to show, a restart button will be visible on the end slide.
rounded	none | pill	Controls rounding of buttons and UI elements.
slide-controls	hide | show	Controls visibility of next and previous buttons.
slide-delimiter	string	Specifies where new slides are created. Default is ---.
submit-button-text	string	Custom text for all submit buttons.
vertical-alignment	start	If set to start, content is aligned to the top of the container vertically.

More settings are available, but they are mainly relevant for full page forms. See the actual code and test cases to learn more.

---

Options

The Formsmd constructor accepts the template of the form, the container where the form will be rendered, and the options to configure form behavior and appearance.

constructor(template: string, container: HTMLElement, options: object)

Example

const formsmd = new Formsmd(
  composer.template,
  document.getElementById("my-form-container"),
  {
    postHeaders: {
      Authorization: `Bearer ${localStorage.getItem("token")}`,
    },
    themeLight: {
      accent: "#353148",
      accentForeground: "#e2d2b6",
      backgroundColor: "#e2d2b6",
      color: "#353148"
    }
  }
);
formsmd.init();

Arguments

Name	Type	Description
template	string	The form template string.
container	HTMLElement	The container element where the form will be rendered.
options	object	Object containing configuration options for form functionality.

Options parameters

The formsmdBranding and/or footer parameters can only be set to "hide" if your site has a Pro subscription (or above).

The options argument can contain the following parameters:

Name	Type	Description
colorScheme	"light" | "dark"	Default or initial color scheme of the form. Default is "light".
errorFieldKey	string	Key used to identify the field in error objects. Default is "field".
errorMessageKey	string	Key used to identify the error message in error objects. Default is "message".
footer	"hide" | "show"	Controls visibility of the footer. Please note, you need a Pro subscription (or above) to hide the footer.
formsmdBranding	"hide" | "show"	Controls visibility of the Forms.md branding. Please note, you need a Pro subscription (or above) to hide the branding.
getHeaders	object	Headers for GET requests.
isFullPage	boolean	Whether to render in full page mode. Default is false.
paddingInlineBottom	number	Padding bottom for inline forms. Default is 20.
paddingInlineHorizontal	number	Horizontal padding for inline forms. Default is 0.
paddingInlineTop	number	Padding top for inline forms. Default is 20.
pageProgress	"hide" | "show" | "decorative"	Controls visibility and function of the page progress.
postData	object	Extra data sent with POST requests.
postHeaders	object	Headers for POST requests.
prioritizeURLFormData	boolean	Whether to prioritize URL form data. Default is false.
recaptcha	object	Option for setting up Google reCAPTCHA for spam protection. Learn more.
sanitize	boolean	Whether to sanitize template. Default is true.
saveState	boolean	Whether to save form data in local storage. Default is true.
sendFilesAsBase64	boolean	Whether to send files as base64. Default is false.
setColorSchemeAttrsAgain	boolean	Whether to set color scheme attributes again.
slideControls	"hide" | "show"	Controls visibility of next and previous buttons.
startSlide	number	The index of the first slide to make active. Default is 0.
themeDark	object	Dark theme colors. Learn more.
themeLight	object	Light theme colors. Learn more.

---

Difference between form settings and options

There is quite a bit of overlap between form settings and options. Generally speaking, form settings are configuration that is unique to that specific form. Options on the other hand, are meant to be shared among multiple or all forms on your website or app. However, this is a soft rule, and it should always come down to convenience and ease of use.

FAQs

How do I run a function after form submission?

How do get my server's submission errors to work?