Composer

Build forms programmatically with the Composer class

The Composer class provides a programmatic way to build Forms.md forms using JavaScript. It generates the Forms.md template syntax from method calls, making it easier to create forms dynamically.

Constructor

Create a new Composer instance with optional settings.

const composer = new Composer(settings);

settings · object

Optional configuration object for the form or page. All properties are optional.

Show settings properties

autofocus · 'all-slides'

When set to "all-slides", the first form field on each slide will be auto-focused when the slide becomes active

accent · string

Primary color for buttons, form fields, etc. Must be HTML name, hex code, or RGB. Supports light/dark mode values

accentForeground · string

Text color on accent background. Must be HTML name, hex code, or RGB

backgroundColor · string

Background color of the page. Must be HTML name, hex code, or RGB

backgroundImage · string

Background image URL for the page

brand · string

Logo image added to the header (must be valid Markdown image syntax)

buttonAlignment · 'center' | 'end' | 'stretch'

Alignment of slide CTA buttons

color · string

Text color for the page. Must be HTML name, hex code, or RGB

colorScheme · 'light' | 'dark' · default: "light"

Default color scheme

colorSchemeScope · 'domain-wide' | 'isolate' · default: "domain-wide"

How color scheme preference is saved and applied

colorSchemeToggle · 'show'

Show color scheme toggle button in footer

cssPrefix · string · default: "fmd-"

Prefix added to all CSS classes

cta · string

Call to action link in header (must be valid Markdown link)

dir · 'ltr' | 'rtl' · default: "ltr"

Text direction

favicon · string

Favicon URL

fieldSize · 'sm'

Make form fields smaller

fontFamily · string

Font family for the page

fontImportUrl · string

URL to import custom fonts (valid CSS @import)

fontSize · 'sm' | 'lg'

Adjust font size for the entire page

formDelimiter · string · default: "|"

Character used to separate form field parameters

formsmdBranding · 'hide' | 'show'

Control visibility of Forms.md branding

formStyle · 'classic'

Use classic form field appearance

footer · 'hide' | 'show'

Control footer visibility

getFormat · 'json' | 'csv' | 'tsv' · default: "json"

Format for reading data

getObjectsName · string · default: "objects"

Name used for objects when reading data

getUrl · string

URL for reading data

header · 'hide' | 'show' | 'align'

Control header visibility and alignment

headings · 'anchored'

Add anchor links to all headings

id · string

Identifier for the page or form

labelStyle · 'classic'

Make form field labels smaller

localization · string · default: "en"

Language for automatic translation (e.g., “en”, “es”, “fr”)

page · 'form-slides' | 'slides' | 'single' · default: "form-slides"

Page layout type

pageProgress · 'hide' | 'show' | 'decorative'

Control page progress indicator

placeholders · 'hide' | 'show'

Control visibility of input placeholders

postSheetName · string

Google Sheets sheet name for saving responses

postUrl · string

URL for sending form responses via POST

restartButton · 'show'

Show restart button

rounded · 'none' | 'pill'

Control rounding of buttons and UI elements

slideControls · 'hide' | 'show'

Control visibility of next/previous buttons

slideDelimiter · string · default: "---"

Delimiter for creating new slides

submitButtonText · string

Custom text for submit buttons

title · string

Page title

verticalAlignment · 'start'

Align content to top of page

template · string

The generated template string. Access via composer.template

Form Input Methods

textInput()

Create a text input field.

composer.textInput('name', {
  question: 'What is your name?',
  required: true,
  placeholder: 'Enter your full name'
});

name · string · required

Field name used for form data

params · object · required

Show params properties

question · string · required

The main question for the form field

required · true

Make the field required

description · string

Extra information to help users fill out the form

placeholder · string

Placeholder text for the input

multiline · true

Use textarea element for multi-line input

maxlength · number

Maximum number of allowed characters

pattern · string

Regex pattern the input value must match

value · string

Default value

fieldSize · 'sm'

Make font sizes smaller

labelStyle · 'classic'

Make question and description smaller

subfield · true

Style as a subfield (smaller text)

disabled · true

Disable the input

autofocus · true

Auto-focus this input

id · string

HTML id attribute

classNames · string[]

CSS class names

attrs · object[]

Additional HTML attributes

Show attr object

name · string · required

Attribute name

value · string · required

Attribute value

displayCondition · object

Conditional display logic

Show displayCondition properties

dependencies · string[] · required

Names of form fields or data used in the condition

condition · string · required

The condition expression

emailInput()

Create an email input field with automatic validation.

composer.emailInput('email', {
  question: 'What is your email?',
  required: true
});

Parameters are the same as textInput() except multiline is not available.

urlInput()

Create a URL input field.

composer.urlInput('website', {
  question: 'What is your website?',
  placeholder: 'https://example.com'
});

Parameters are the same as textInput() except multiline is not available.

telInput()

Create a telephone input field with country code selector.

composer.telInput('phone', {
  question: 'What is your phone number?',
  required: true,
  country: 'US',
  availableCountries: ['US', 'CA', 'GB']
});

country · string · default: "US"

Default country code (e.g., “US”, “GB”, “FR”)

availableCountries · string[]

Array of available country codes

Other parameters are the same as textInput() except multiline is not available.

passwordInput()

Create a password input field.

composer.passwordInput('password', {
  question: 'Create a password',
  required: true,
  minlength: 8
});

Parameters are the same as textInput() except multiline is not available.

numberInput()

Create a number input field.

composer.numberInput('age', {
  question: 'What is your age?',
  required: true,
  min: 18,
  max: 120
});

min · number

Minimum allowed value

max · number

Maximum allowed value

step · number

Stepping interval

unit · string

Text displayed before the input (e.g., ”$”, ”€”)

unitEnd · string

Text displayed after the input (e.g., “kg”, ”%”)

value · number

Default value

selectBox()

Create a select dropdown field.

composer.selectBox('country', {
  question: 'Select your country',
  required: true,
  options: [
    'United States',
    'Canada',
    { label: 'United Kingdom', value: 'UK' }
  ],
  placeholder: 'Choose a country'
});

options · array · required

Array of options. Each option can be a string or an object with label and optional value

placeholder · string

Placeholder text for the select

selected · string

Pre-selected option value

choiceInput()

Create a choice field with radio buttons or checkboxes.

composer.choiceInput('interests', {
  question: 'What are your interests?',
  choices: ['Reading', 'Sports', 'Music', 'Travel'],
  multiple: true,
  horizontal: true
});

choices · array · required

Array of choices. Each choice can be a string or an object with label and optional value

multiple · true

Allow multiple selections (uses checkboxes instead of radio buttons)

horizontal · true

Display choices horizontally

hideFormText · true

Hide the form text

checked · string[]

Array of pre-checked choice values

pictureChoice()

Create a picture choice field.

composer.pictureChoice('theme', {
  question: 'Choose your theme',
  choices: [
    { label: 'Light', value: 'light', image: 'light.jpg' },
    { label: 'Dark', value: 'dark', image: 'dark.jpg' }
  ]
});

choices · array · required

Array of picture choices. Each must have label, image URL, and optional value

multiple · true

Allow multiple selections

supersize · true

Make pictures larger

hideLabels · true

Hide text labels

hideFormText · true

Hide the form text

checked · string[]

Array of pre-checked choice values

ratingInput()

Create a rating input field.

composer.ratingInput('satisfaction', {
  question: 'How satisfied are you?',
  required: true,
  outOf: 5,
  icon: 'star'
});

outOf · number · default: "5"

Number of rating options (1-10)

icon · 'star' | 'heart' | 'hearts' · default: "star"

Icon to use for rating

value · number

Pre-selected rating value

hideLabels · true

Hide numeric labels

opinionScale()

Create an opinion scale field.

composer.opinionScale('likelihood', {
  question: 'How likely are you to recommend us?',
  required: true,
  startAt: 0,
  outOf: 10,
  labelStart: 'Not likely',
  labelEnd: 'Very likely'
});

startAt · number · default: "0"

Starting number (0 or 1)

outOf · number · default: "10"

Maximum scale value (5-10)

labelStart · string

Label for the start of the scale

labelEnd · string

Label for the end of the scale

hideLabelStart · true

Hide the start label

hideLabelEnd · true

Hide the end label

value · number

Pre-selected value

datetimeInput()

Create a datetime input field.

composer.datetimeInput('appointment', {
  question: 'When would you like to schedule?',
  required: true,
  min: '2024-01-01T09:00',
  max: '2024-12-31T17:00'
});

min · string

Minimum datetime (format: “YYYY-MM-DDTHH:mm”)

max · string

Maximum datetime (format: “YYYY-MM-DDTHH:mm”)

step · string

Stepping interval

value · string

Pre-selected datetime

dateInput()

Create a date input field.

composer.dateInput('birthday', {
  question: 'What is your date of birth?',
  required: true,
  max: '2024-12-31'
});

min · string

Minimum date (format: “YYYY-MM-DD”)

max · string

Maximum date (format: “YYYY-MM-DD”)

value · string

Pre-selected date

timeInput()

Create a time input field.

composer.timeInput('meetingTime', {
  question: 'What time works best?',
  required: true,
  min: '09:00',
  max: '17:00'
});

min · string

Minimum time (format: “HH:mm”)

max · string

Maximum time (format: “HH:mm”)

value · string

Pre-selected time

fileInput()

Create a file upload field.

composer.fileInput('resume', {
  question: 'Upload your resume',
  required: true,
  sizeLimit: 5,
  imageOnly: true
});

sizeLimit · number · default: "10"

Maximum file size in MB

imageOnly · true

Only accept image files

currentFile · string

URL of existing file (for edit forms)

Slide Methods

slide()

Create a new slide.

composer.slide({
  jumpCondition: 'age >= 18',
  pageProgress: '1/3',
  post: true
});

params · object

Show params properties

jumpCondition · string

Logic jump condition - slide only shown when condition is true

pageProgress · string

Custom progress indicator (e.g., “50%” or “1/2”)

buttonAlignment · 'start' | 'center' | 'end' | 'stretch'

Alignment of this slide’s CTA button

post · true

Post form data when going to next slide

disablePrevious · true

Disable the previous button on this slide

startSlide()

Create a start slide (first slide with a start button).

composer.startSlide({
  buttonText: 'Get Started',
  buttonAlignment: 'center'
});

buttonText · string

Custom text for the start button

buttonAlignment · 'start' | 'center' | 'end' | 'stretch'

Alignment of the start button

endSlide()

Create an end slide (final slide after form submission).

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

redirectUrl · string

URL to redirect to from the end slide

Content Methods

dataBlock()

Create a data block to define variables.

composer.dataBlock({
  companyName: 'Acme Inc',
  products: ['Widget', 'Gadget', 'Doohickey']
});

data · object · required

Object containing data to make available in the form

free()

Add free-form Markdown content.

composer.free('## Welcome\n\nThank you for taking our survey!');

content · string · required

Markdown content to add

p()

Create a paragraph.

composer.p('This is a paragraph of text.', {
  id: 'intro',
  classNames: ['highlight']
});

h1() - h6()

Create headings.

composer.h1('Main Title');
composer.h2('Subtitle', { id: 'subtitle' });
composer.h3('Section');

content · string · required

Heading text

params · object

Optional id, classNames, and attrs

ul()

Create an unordered list.

composer.ul([
  'First item',
  'Second item',
  'Third item'
]);

items · string[] · required

Array of list items

ol()

Create an ordered list.

composer.ol([
  'Step one',
  'Step two',
  'Step three'
]);

items · string[] · required

Array of list items

blockquote()

Create a blockquote.

composer.blockquote('This is a quote.\nWith multiple lines.');

content · string · required

Quote content

code()

Create a code block.

composer.code('const x = 10;\nconsole.log(x);', {
  language: 'javascript'
});

content · string · required

Code content

params.language · string

Programming language for syntax highlighting

hr()

Create a horizontal rule.

composer.hr();

div()

Create a div container.

composer.div('Content inside div', {
  classNames: ['container'],
  bind: ['name', 'email']
});

content · string · required

Content inside the div

params.bind · string[]

Array of form fields to bind for reactive updates

divStart() / divEnd()

Create div start and end tags separately.

composer.divStart({ classNames: ['wrapper'] });
composer.p('Content');
composer.divEnd();

Example

import { Composer } from '@formsmd/composer';

const composer = new Composer({
  title: 'Customer Survey',
  accent: 'blue'
});

composer.startSlide();
composer.h1('Welcome!');
composer.p('Thank you for your time.');

composer.slide();
composer.textInput('name', {
  question: 'What is your name?',
  required: true
});

composer.emailInput('email', {
  question: 'What is your email?',
  required: true
});

composer.slide();
composer.ratingInput('satisfaction', {
  question: 'How satisfied are you?',
  required: true,
  outOf: 5
});

composer.endSlide();
composer.h2('Thank you!');
composer.p('We appreciate your feedback.');

const template = composer.template;