# Email input

<figure><img src="https://824814026-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRq8uKg8VhNAvWTRL52uz%2Fuploads%2FLaa5YalAl7YKGIVHep3j%2Femail-input.png?alt=media&#x26;token=05d4aaf5-7295-418e-9497-c4cb87a0cb93" alt=""><figcaption><p>Email input</p></figcaption></figure>

Use the `emailInput()` function to create email inputs in your forms. It uses the HTML `<input type="email">` element which provides built-in email validation.

***

## Basic usage

```javascript
import { Composer } from "formsmd";

const composer = new Composer({
  id: "my-form"
});

composer.emailInput("email", {
  question: "What is your email address?"
});
```

Generates the following Markdown-like syntax:

```
#! id = my-form

email = EmailInput(
  | question = What is your email address?
)
```

### Required

Add the `required` parameter to make the field mandatory:

```javascript
composer.emailInput("email", {
  question: "What is your email address?",
  required: true
});
```

Generates the following Markdown-like syntax:

```
email* = EmailInput(
  | question = What is your email address?
)
```

***

## Function overview

The following is the overview of the function:

```typescript
emailInput(name: string, params: object)
```

### Arguments

| Name     | Type     | Description                                                                                                                                                      |
| -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`   | `string` | A unique name for your form field that you'll use to identify the user's response.<mark style="color:red;">\*</mark>                                             |
| `params` | `object` | An object containing all the configuration parameters for your email input field (see the [parameters section](#parameters) below for the full list of options). |

{% hint style="danger" %} <mark style="color:red;">\*</mark>Avoid values for the `name` argument which may be the names of HTML attributes, such as `"name"`, `"role"`, `"id"`, etc. This is because by default, the form's template string is first sanitized using [DOMPurify](https://github.com/cure53/DOMPurify), and these values may be removed to prevent DOM clobbering.
{% endhint %}

***

## Parameters

### Shared parameters

These parameters are common to all form fields:

| Name                  | Type                                            | Description                                                                                                                                                                                                                                                                             |
| --------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `question` (required) | `string`                                        | The main question or label of the form field.                                                                                                                                                                                                                                           |
| `required`            | `true` (`boolean`)                              | When set, the field becomes required.                                                                                                                                                                                                                                                   |
| `description`         | `string`                                        | Any extra information that the user may need to fill out the form. Appears right below the question.                                                                                                                                                                                    |
| `fieldSize`           | `"sm"`                                          | When set to `"sm"`, the font sizes of the question, description, and answer are made smaller.                                                                                                                                                                                           |
| `labelStyle`          | `"classic"`                                     | When set to `"classic"`, the question and description of the form field are made smaller.                                                                                                                                                                                               |
| `subfield`            | `true` (`boolean`)                              | When set, the question and description of the form field are made smaller. Functionally the same as setting `labelStyle` to `"classic"`.                                                                                                                                                |
| `disabled`            | `true` (`boolean`)                              | When set, the input is disabled.                                                                                                                                                                                                                                                        |
| `autofocus`           | `true` (`boolean`)                              | When set, the input will be automatically focused when the parent slide becomes active, or immediately after page load.                                                                                                                                                                 |
| `id`                  | `string`                                        | The `id` attribute of the form field container.                                                                                                                                                                                                                                         |
| `classNames`          | `string[]`                                      | The CSS class names of the form field. [See the available CSS utility classes](https://docs.forms.md/content/css-utility-classes).                                                                                                                                                      |
| `attrs`               | `Array<{ name: string, value: string }>`        | Other HTML attributes of the form field. Each attribute has a `name` and `value` property.                                                                                                                                                                                              |
| `displayCondition`    | `{ dependencies: string[], condition: string }` | Controls when the field is shown. The `dependencies` lists the fields to watch, and `condition` is the expression that must be true to show the field. The `condition` must be a valid [Nunjucks](https://mozilla.github.io/nunjucks/) expression. [See example](#conditional-display). |

### Email input specific parameters

| Name          | Type     | Description                                                                 |
| ------------- | -------- | --------------------------------------------------------------------------- |
| `placeholder` | `string` | Sets the `placeholder` attribute of the input.                              |
| `maxlength`   | `number` | If set, this becomes the maximum number of allowed characters in the input. |
| `pattern`     | `string` | If set, the input value must match the given pattern.                       |
| `value`       | `string` | If set, this becomes the default value of the input.                        |

***

## Examples

### Email input with custom placeholder

```javascript
composer.emailInput("contactEmail", {
  question: "What's your email address?",
  description: "We'll send the confirmation to this email",
  placeholder: "you@example.com",
  required: true
});
```

Generates the following Markdown-like syntax:

```
contactEmail* = EmailInput(
  | question = What's your email address?
  | description = We'll send the confirmation to this email
  | placeholder = you@example.com
)
```

### Email input with pattern validation

```javascript
composer.emailInput("workEmail", {
  question: "Work email address",
  description: "Please use your company email",
  pattern: ".*@company\\.com$",
  required: true
});
```

Generates the following Markdown-like syntax:

```
workEmail* = EmailInput(
  | question = Work email address
  | description = Please use your company email
  | pattern = .*@company\.com$
)
```

### Styled email input with custom attributes

Add CSS classes and other HTML attributes using the `classNames` and `attrs` parameters. Please note, these class names and attributes are added to the `<div>` or `<fieldset>` container that contains the actual input field(s).

```javascript
composer.emailInput("emailAddress", {
  question: "Email address",
  classNames: ["col-6", "xs:col-6"],
  attrs: [
    { name: "style", value: "font-size: 18px;" }
  ]
});
```

Generates the following Markdown-like syntax:

```
[.col-6 .xs:col-6 style="font-size: 18px;"]
emailAddress = EmailInput(
  | question = Email address
)
```

Please [see the available CSS utility classes](https://docs.forms.md/content/css-utility-classes).

### Conditional display

Conditionally show or hide an email input field using the `displayCondition` parameter. It works as follows:

* `dependencies` lists the fields to watch.
* `condition` is the expression that must be true to show the field. This must be a valid [Nunjucks](https://mozilla.github.io/nunjucks/) expression.

For instance, in the example below, the alternate email input will only show up if the user indicates they want to provide one.

```javascript
composer.choiceInput("wantAlternateEmail", {
  question: "Would you like to provide an alternate email?",
  required: true,
  choices: ["Yes", "No"]
})

composer.emailInput("alternateEmail", {
  question: "Alternate email address",
  displayCondition: {
    dependencies: ["wantAlternateEmail"],
    condition: "wantAlternateEmail == 'Yes'"
  }
});
```

Generates the following Markdown-like syntax:

```
wantAlternateEmail* = ChoiceInput(
  | question = Would you like to provide an alternate email?
  | choices = Yes, No
)

::: [{$ wantAlternateEmail $}]
{% if wantAlternateEmail == "Yes" %}
alternateEmail = EmailInput(
  | question = Alternate email address
)
{% endif %}
:::
```