152 lines
4.6 KiB
Markdown
152 lines
4.6 KiB
Markdown
---
|
|
title: "Email Field"
|
|
aliases: [payload-email-field, email-field-payloadcms]
|
|
tags: [payloadcms, fields, email, validation]
|
|
sources: [raw/fields__email.md]
|
|
created: 2026-05-15
|
|
updated: 2026-05-15
|
|
---
|
|
|
|
## Overview
|
|
|
|
The Email field enforces that the stored value is a valid email address. It renders a standard email input in the Admin Panel with built-in format validation on both client and server.
|
|
|
|
```ts
|
|
import type { Field } from 'payload'
|
|
|
|
export const MyEmailField: Field = {
|
|
name: 'contact',
|
|
type: 'email',
|
|
}
|
|
```
|
|
|
|
## Key Takeaways
|
|
|
|
- `type: 'email'` — built-in email format validation, no custom validator needed for basic use
|
|
- Inherits all base field options: `required`, `unique`, `index`, `localized`, `hidden`, `defaultValue`, `hooks`, `access`, `saveToJWT`, `virtual`
|
|
- `unique: true` creates a **database-level unique index** on the field path
|
|
- `index: true` — add if you query by email frequently (e.g. user lookup)
|
|
- `saveToJWT: true` — embeds email into JWT/cookie; useful for reading email in access control without a DB round-trip (see [[wiki/payloadcms/authentication-token-data|Token Data]])
|
|
- `virtual: true` — field is not persisted to DB; use for computed or derived email values
|
|
|
|
## Config Options
|
|
|
|
| Option | Description |
|
|
|--------|-------------|
|
|
| `name` * | DB property name |
|
|
| `label` | Admin panel label (string or per-locale object) |
|
|
| `unique` | DB-level unique index |
|
|
| `index` | Query performance index |
|
|
| `validate` | Custom validation function (client + server) |
|
|
| `saveToJWT` | Include in user JWT token |
|
|
| `hooks` | Field lifecycle hooks |
|
|
| `access` | Field-level access control |
|
|
| `hidden` | Exclude from API and admin UI (still stored in DB) |
|
|
| `defaultValue` | Default email value |
|
|
| `localized` | Enable per-locale storage (requires global localization config) |
|
|
| `required` | Make field mandatory |
|
|
| `admin` | Admin UI options (see below) |
|
|
| `virtual` | Skip DB persistence; or path string to link to a relationship |
|
|
|
|
## Admin Options
|
|
|
|
```ts
|
|
admin: {
|
|
placeholder: 'user@example.com',
|
|
autoComplete: 'email',
|
|
}
|
|
```
|
|
|
|
| Property | Description |
|
|
|----------|-------------|
|
|
| `placeholder` | Placeholder string shown in the input |
|
|
| `autoComplete` | Browser autocomplete attribute value |
|
|
|
|
Plus all standard [[wiki/payloadcms/fields-basic|base field admin options]].
|
|
|
|
## Example — Full Config
|
|
|
|
```ts
|
|
import type { CollectionConfig } from 'payload'
|
|
|
|
export const Contacts: CollectionConfig = {
|
|
slug: 'contacts',
|
|
fields: [
|
|
{
|
|
name: 'contact',
|
|
type: 'email',
|
|
label: 'Contact Email Address',
|
|
required: true,
|
|
unique: true,
|
|
index: true,
|
|
saveToJWT: false,
|
|
admin: {
|
|
placeholder: 'user@example.com',
|
|
autoComplete: 'email',
|
|
},
|
|
},
|
|
],
|
|
}
|
|
```
|
|
|
|
## Custom Components
|
|
|
|
### Field — Server
|
|
|
|
```tsx
|
|
import type { EmailFieldServerComponent } from 'payload'
|
|
import { EmailField } from '@payloadcms/ui'
|
|
|
|
export const CustomEmailFieldServer: EmailFieldServerComponent = ({
|
|
clientField, path, schemaPath, permissions,
|
|
}) => (
|
|
<EmailField field={clientField} path={path} schemaPath={schemaPath} permissions={permissions} />
|
|
)
|
|
```
|
|
|
|
### Field — Client
|
|
|
|
```tsx
|
|
'use client'
|
|
import type { EmailFieldClientComponent } from 'payload'
|
|
import { EmailField } from '@payloadcms/ui'
|
|
|
|
export const CustomEmailFieldClient: EmailFieldClientComponent = (props) => (
|
|
<EmailField {...props} />
|
|
)
|
|
```
|
|
|
|
### Label — Server
|
|
|
|
```tsx
|
|
import type { EmailFieldLabelServerComponent } from 'payload'
|
|
import { FieldLabel } from '@payloadcms/ui'
|
|
|
|
export const CustomEmailFieldLabelServer: EmailFieldLabelServerComponent = ({ clientField, path }) => (
|
|
<FieldLabel label={clientField?.label || clientField?.name} path={path} required={clientField?.required} />
|
|
)
|
|
```
|
|
|
|
### Label — Client
|
|
|
|
```tsx
|
|
'use client'
|
|
import type { EmailFieldLabelClientComponent } from 'payload'
|
|
import { FieldLabel } from '@payloadcms/ui'
|
|
|
|
export const CustomEmailFieldLabelClient: EmailFieldLabelClientComponent = ({ field, path }) => (
|
|
<FieldLabel label={field?.label || field?.name} path={path} required={field?.required} />
|
|
)
|
|
```
|
|
|
|
## Related
|
|
|
|
- [[wiki/payloadcms/fields-basic|Fields: Basic]] — all scalar field types overview
|
|
- [[wiki/payloadcms/authentication-token-data|Authentication — Token Data]] — use `saveToJWT` to embed email into JWT
|
|
- [[wiki/payloadcms/database-indexes|Database Indexes]] — `unique` and `index` internals
|
|
- [[wiki/payloadcms/authentication-overview|Authentication Overview]] — Users collection with email auth
|
|
- [[wiki/payloadcms/custom-components-authoring|Custom Components Authoring]] — RSC vs Client component rules
|
|
|
|
---
|
|
|
|
*Source: raw/fields__email.md — https://payloadcms.com/docs/fields/email*
|