# Slide

## 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](/content/end-slide.md).

<div><figure><img src="/files/lqPiqI6V5uQ62FSkzjFq" alt=""><figcaption><p>Slide 1</p></figcaption></figure> <figure><img src="/files/Wkm4C9jtLwve9ND054yo" alt=""><figcaption><p>Slide 2</p></figcaption></figure> <figure><img src="/files/PHbgWWAh6GCkGDtAoHGr" alt=""><figcaption><p>Slide 3 (only shown if the user was recommended)</p></figcaption></figure></div>

```javascript
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:

```typescript
slide(params: object)
```

### Arguments

| Name     | Type     | Description                                                                                                                                          |
| -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `params` | `object` | An object containing all the configuration parameters for your slide (see the [parameters section](#parameters) 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](https://mozilla.github.io/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](#slide-level-or-partial-submission). |
| `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](https://mozilla.github.io/nunjucks/) expression.

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

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

```javascript
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](/getting-started/settings.md) (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`.

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

```javascript
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

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.forms.md/content/slide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.