Slide

Add slides to easily create multi-step forms.

Basic usage

The slide() function creates a new slide at the point where it is called. This means that anything after this function will be placed automatically within a new slide, until another slide() function is called (which would create another new slide), and so on. Each slide can contain form fields, content, and custom settings like logic jumps, progress indicators, etc.

In the example below, the second slide will contain the referralSource and have the progress indicator set to half-complete (or 50%). The third slide will contain the recommender, but it will only be shown to the user if they pick "Recommendation" in the second slide. An end slide with a thank you message is automatically added to every form, though this can be customized.

Slide 1

Slide 2

Slide 3 (only shown if the user was recommended)

import { Composer } from "formsmd";

const composer = new Composer({
  id: "my-form"
});
 
composer.choiceInput("position", {
  question: "What's your position?",
  choices: ["Product Manager", "Software Engineer", "Founder", "Other"],
  required: true
});

// Start new slide, progress indicator at 50%
composer.slide({
  pageProgress: "50%"
});

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%"
});

composer.emailInput("recommender", {
  question: "Who recommended you?"
});

Generates the following Markdown-like syntax:

#! id = my-form

position* = ChoiceInput(
  | question = What's your position?
  | choices = Product Manager, Software Engineer, Founder, Other
)

---
|> 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?
)

---

Function overview

The following is the overview of the function:

slide(params: object)

Arguments

Name	Type	Description
params	object	An object containing all the configuration parameters for your slide (see the parameters section below for the full list of options).

---

Parameters

Name	Type	Description
jumpCondition	string	Logic jump condition that must be true for slide to be shown. This must be a valid Nunjucks expression.
pageProgress	string	Progress indicator shown on top (e.g. "50%" or "1/2"). Format is percentage or fraction.
buttonAlignment	"start" | "center" | "end" | "stretch"	Set the alignment of this slide's CTA button.
post	true (boolean)	Can be used for slide-level or partial submissions. When set, posts form data up to this slide when going to the next one. See example.
disablePrevious	true (boolean)	When set, disables the previous button.

---

Examples

Slide with logic jump

In the example below, the second slide will only be shown to the user if they are older than 18. Please note, the jumpCondition parameter must be a valid Nunjucks expression.

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

composer.slide({
  jumpCondition: "age > 18"
});

composer.textInput("drivingLicense", {
  question: "What is your driving license number?",
  required: true
});

Generates the following Markdown-like syntax:

age* = NumberInput(
  | question = What is your age?
  | min = 0
  | max = 120
)

---
-> age > 18

drivingLicense* = TextInput(
  | question = What is your driving license number?
)

Slide with progress indicator

In the example below, the progress indicator will be set to half-complete (or 50%) within the second slide because of the pageProgress parameter.

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

composer.slide({
  pageProgress: "50%"
});

composer.telInput("phone", {
  question: "What is your phone number?"
});

Generates the following Markdown-like syntax:

name* = TextInput(
  | question = What is your full name?
)

---
|> 50%

phone = TelInput(
  | question = What is your phone number?
)

Slide with button alignment

In the example below, the submit button will be centered within the second slide because of the buttonAlignment parameter.

composer.textInput("companyName", {
  question: "What is your company name?",
  required: true
});

composer.slide({
  buttonAlignment: "center"
});

composer.numberInput("employees", {
  question: "How many employees work at your company?",
  min: 1
});

Generates the following Markdown-like syntax:

companyName* = TextInput(
  | question = What is your company name?
)

---
=| center

employees = NumberInput(
  | question = How many employees work at your company?
  | min = 1
)

Please note, this slide-level buttonAlignment parameter will take precedence over the buttonAligment form setting (which can be used to set the button alignment of every single slide globally).

Slide-level or partial submission

A slide-level or partial submission is when the user completes a slide and goes to the next one, all the form data up to that slide will be sent to the POST URL. Use the post parameter to do slide-level submissions. In the example below, when the user enters their email and goes to the next slide, their accountEmail will be sent to /api/verify-email. Once they enter the verificationCode, the form data will again be sent to /api/verify-email.

import { Composer } from "formsmd";

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

composer.slide({
  post: true
});

composer.emailInput("accountEmail", {
  question: "Enter your account email",
  required: true
});

composer.slide({});

composer.numberInput("verificationCode", {
  question: "Enter the verification code sent to your email",
  required: true,
  min: 100000,
  max: 999999
});

Generates the following Markdown-like syntax:

#! id = my-form
#! post-url = /api/verify-email

>> post

accountEmail* = EmailInput(
  | question = Enter your account email
)

---
verificationCode* = NumberInput(
  | question = Enter the verification code sent to your email
  | min = 100000
  | max = 999999
)

Slide with disabled previous button

In the example below, the previous button (in the footer) will be disabled within the second slide because of the disablePrevious parameter.

composer.choiceInput("acceptTerms", {
  question: "Do you accept the terms of service?",
  required: true,
  choices: ["Yes", "No"]
});

composer.slide({
  disablePrevious: true
});

composer.textInput("signature", {
  question: "Please type your full name as signature",
  required: true
});

Generates the following Markdown-like syntax:

acceptTerms* = ChoiceInput(
  | question = Do you accept the terms of service?
  | choices = Yes, No
)

---
<< disable

signature* = TextInput(
  | question = Please type your full name as signature
)

Slide with multiple parameters

composer.choiceInput("accountType", {
  question: "What type of account would you like to create?",
  required: true,
  choices: ["personal", "business"]
});

composer.slide({
  jumpCondition: "accountType == 'business'",
  pageProgress: "75%",
  buttonAlignment: "end"
});

composer.textInput("businessName", {
  question: "What is your business name?",
  required: true
});

Generates the following Markdown-like syntax:

accountType* = ChoiceInput(
  | question = What type of account would you like to create?
  | choices = personal, business
)

---
-> accountType == "business"
|> 75%
=| end

businessName* = TextInput(
  | question = What is your business name?
)