> ## Documentation Index
> Fetch the complete documentation index at: https://docs.awaitio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Input Email

> Asks for an email address.

`io.input.email()` requests an email address and returns it as a string. Provided by the `@awaitio/input-email` package.

<Frame>
  <img src="https://mintcdn.com/awaitio/MjbT5AW66vMXbVck/images/io-input-email.png?fit=max&auto=format&n=MjbT5AW66vMXbVck&q=85&s=4a771c13de4f0f992fc826c0d050f8f1" alt="An Email field filled with ada@example.com, with help text under it" width="1004" height="212" data-path="images/io-input-email.png" />
</Frame>

## Install

```bash theme={null}
npm install @awaitio/input-email
```

## Setup

Register it under the key you want in `io`, see [Input components](/core/components):

```ts app.ts {5} theme={null}
import { inputEmail } from '@awaitio/input-email';

export const app = new AwaitIO({
  // name, actionsDirectory, theme, secret, users…
  components: { input: { email: inputEmail } },
});
```

## Usage

```ts theme={null}
const ownerEmail = await io.input.email('Owner email', {
  placeholder: 'ada@example.com',
  helpText: 'Gets the invitation',
});
```

## Props

| Prop | Type | Required | Description |
| - | - | - | - |
| `placeholder` | `string` | Optional | Text shown in the empty field. |
| `helpText` | `string` | Optional | Secondary text under the field. |
| `defaultValue` | `string` | Optional | The value the field starts with. Defaults to an empty string. |
| `disabled` | `boolean` | Optional | Shows the starting value without letting it change; the handler gets that value whatever the browser sends. |

## Optional

The field is required. Chain `.optional()` to let it stay empty; the handler then gets `string | undefined`, see [Optional fields](/core/components#optional-fields).

```ts theme={null}
const backupEmail = await io.input.email('Backup email').optional();
```

## Returns

`string`: the address without the spaces around it.

## Built-in validation

The browser checks the format before sending, and the server checks every answer again:

| When | Message |
| - | - |
| The field is empty or not an email address | `<label>: enter an email address.` |

## Custom validation

Chain `.validate()` for a check of your own. It runs on the server after the checks above, gets the value the handler would get and returns a message to show under the field, or nothing when the value is fine; see [Custom validation](/core/components#custom-validation).

```ts theme={null}
const email = await io.input.email('Work email').validate((email) => {
  return email.endsWith('@acme.com') ? undefined : 'Use your @acme.com address.';
});
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.