Composer

Build form templates programmatically with the Composer class

The Composer class is your primary tool for creating form templates programmatically. It provides a chainable API for building multi-step forms with form fields, slides, and conditional logic.

Overview

Composer generates a Forms.md template string that you pass to the Formsmd class for rendering. All methods are chainable and append to an internal template property.

import { Composer } from "formsmd";

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

Constructor

Create a new Composer instance with optional settings:

const composer = new Composer(settings);

Settings type

The constructor accepts a SettingsType object with the following properties:

View all settings properties

Property	Type	Description
id	string	Identifier for the page or form
postUrl	string	URL to send form responses to using POST request
page	"form-slides" | "slides" | "single"	Determines the layout of the page
slideDelimiter	string	Specifies where new slides are created (default: "---")
formDelimiter	string	Used to separate parameters when creating form fields (default: `"	"`)
accent	string	The primary color used on buttons, form fields, etc.
backgroundColor	string	The background color of the page
color	string	The text color on the page
title	string	The title of the page
localization	string	Sets the language for automatic translation (default: "en")
pageProgress	"hide" | "show" | "decorative"	Controls visibility and function of the page progress

And many more… See the full type definition in types/composer.d.ts

Creating form fields

Composer provides methods for all Forms.md form field types. Each method accepts a field name and a params object.

Text input

src/composer.js

composer.textInput("fullName", {
  question: "What's your full name?",
  required: true,
  placeholder: "John Doe"
});

Email input

src/composer.js

composer.emailInput("email", {
  question: "What's your email address?",
  required: true,
  description: "We'll never share your email with anyone."
});

Choice input

src/composer.js

composer.choiceInput("role", {
  question: "What's your role?",
  choices: ["Developer", "Designer", "Product Manager"],
  required: true,
  multiple: true  // Allow multiple selections
});

Number input

src/composer.js

composer.numberInput("budget", {
  question: "What's your budget?",
  unit: "$",
  min: 0,
  max: 10000,
  step: 100
});

All form field methods share common parameters like question, required, description, fieldSize, labelStyle, disabled, autofocus, id, classNames, and displayCondition.

Available form field methods

textInput

Create a text input field with optional multiline support

emailInput

Create an email input with built-in validation

urlInput

Create a URL input field

telInput

Create a telephone input with country code selector

passwordInput

Create a password input field

numberInput

Create a number input with min/max/step controls

selectBox

Create a dropdown select field

choiceInput

Create radio buttons or checkboxes

pictureChoice

Create image-based choice options

ratingInput

Create a star/heart rating input

opinionScale

Create an opinion scale (e.g., 0-10)

datetimeInput

Create a datetime picker

dateInput

Create a date picker

timeInput

Create a time picker

fileInput

Create a file upload field

Method chaining

All Composer methods return the generated template string and also append it to composer.template, enabling clean method chaining:

const composer = new Composer({ id: "survey" });

composer
  .textInput("name", { question: "Your name?", required: true })
  .emailInput("email", { question: "Your email?", required: true })
  .slide({ pageProgress: "50%" })
  .ratingInput("satisfaction", { 
    question: "How satisfied are you?",
    outOf: 5,
    icon: "star"
  });

// Use the template
const formsmd = new Formsmd(
  composer.template,
  document.getElementById("container")
);

Shared field parameters

All form fields accept these shared parameters from the FormFieldSharedParamsType:

Common parameters

{
  question: "The main question text",           // Required
  required: true,                                 // Makes field required
  description: "Additional help text",           // Optional description
  fieldSize: "sm",                               // Smaller field size
  labelStyle: "classic",                         // Classic label styling
  subfield: true,                                // Render as subfield
  disabled: true,                                // Disable the input
  autofocus: true,                               // Auto-focus on slide load
  id: "custom-id",                               // Custom HTML id
  classNames: ["custom-class"],                  // CSS class names
  attrs: [{ name: "data-test", value: "field" }], // Custom HTML attributes
  displayCondition: {                            // Conditional display
    dependencies: ["otherField"],
    condition: "otherField == 'value'"
  }
}

Creating slides

Use the slide() method to create new slides in multi-step forms:

src/composer.js

composer.slide({
  pageProgress: "50%",           // Show progress indicator
  jumpCondition: "age >= 18",    // Conditional display
  buttonAlignment: "center",      // Button alignment
  post: true,                     // POST data when leaving
  disablePrevious: true           // Disable back button
});

Slides are created wherever you call composer.slide(). Form fields added after a slide call belong to that slide.

Special slide types

Start slide

Create a welcome/intro slide with a custom start button:

src/composer.js

composer.startSlide({
  buttonText: "Begin Survey",
  buttonAlignment: "center"
});

End slide

Create a completion slide with optional redirect:

src/composer.js

composer.endSlide({
  redirectUrl: "https://example.com/thank-you"
});

Additional methods

Data blocks

Embed data directly in the template:

src/composer.js

composer.dataBlock({
  products: [
    { id: 1, name: "Product A" },
    { id: 2, name: "Product B" }
  ]
});

Free-form content

Add custom Markdown content:

src/composer.js

composer.free(`
# Welcome to our survey

Please take a few moments to answer these questions.
`);

Block elements

Create semantic HTML elements:

composer.p("This is a paragraph", { 
  classNames: ["lead"] 
});

composer.h1("Main Heading");
composer.h2("Subheading");

Accessing the template

The generated template is available in the template property:

const composer = new Composer({ id: "my-form" });
composer.textInput("name", { question: "Name?" });

console.log(composer.template);
// Output:
// #! id = my-form
// 
// name* = TextInput(
//   | question = Name?
// )

Next steps

Formsmd class

Learn how to render your templates

Slides

Create multi-step forms with slides

Conditional logic

Add dynamic behavior to your forms