LogoLogo
WebsitePricingGitHubSign up
  • Getting started
    • Installation and usage
    • Form settings
    • Options
    • Frequently asked questions
    • Spam protection
    • React
  • Customization
    • Theming
    • Localization
  • Input types
    • Text input
    • Email input
    • URL input
    • Telephone input
    • Password input
    • Number input
    • Select box
    • Choice input
    • Picture choice
    • Rating input
    • Opinion scale / Net Promoter ScoreĀ®
    • Datetime input
    • Date input
    • Time input
    • File input
  • Content
    • Slide
    • Start slide
    • End slide
    • Markdown
    • Data binding
    • CSS utility classes
  • Integrations
    • Google Sheets integration
Powered by GitBook

Ā© 2025 Forms.md | All rights reserved

On this page
  • Installation
  • Install via npm
  • Use in browser
  • Usage
  • Form settings
  • Example
  • Arguments
  • Settings parameters
  • Options
  • Example
  • Arguments
  • Options parameters
  • Difference between form settings and options
  • FAQs
  • How do I run a function after form submission?
  • How do get my server's submission errors to work?

Was this helpful?

  1. Getting started

Installation and usage

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

NextForm settings

Last updated 3 months ago

Was this helpful?

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 . 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.

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();
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();

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

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"

formStyle

"classic"

If set to "classic", the form fields will have a classic appearance.

footer

"hide" | "show"

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.

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

form-style

classic

If set to classic, the form fields will have a classic appearance.

footer

hide | show

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 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"

formsmdBranding

"hide" | "show"

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

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

themeLight

object


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

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

Controls visibility of the Forms.md branding. Please note, you need a (or above) to hide the branding.

Controls visibility of the footer. Please note, you need a (or above) to hide the footer.

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

Controls visibility of the Forms.md branding. Please note, you need a (or above) to hide the branding.

Controls visibility of the footer. Please note, you need a (or above) to hide the footer.

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

Controls visibility of the footer. Please note, you need a (or above) to hide the footer.

Controls visibility of the Forms.md branding. Please note, you need a (or above) to hide the branding.

Option for setting up Google reCAPTCHA for spam protection. .

Dark theme colors. .

Light theme colors. .

the GitHub repo
Pro subscription
Pro subscription
Pro subscription
How do I run a function after form submission?
How do get my server's submission errors to work?
Pro subscription
Pro subscription
Pro subscription
Pro subscription
Pro subscription
Pro subscription
Learn more
Learn more
Learn more
Slide 1 when "Other" is picked
Slide 2
Slide 3 (only shown if the user was recommended)