diff --git a/raw/fields__email.md b/raw/_processed/fields__email.md similarity index 100% rename from raw/fields__email.md rename to raw/_processed/fields__email.md diff --git a/wiki/_master-index.md b/wiki/_master-index.md index af20eab..d725f3e 100644 --- a/wiki/_master-index.md +++ b/wiki/_master-index.md @@ -35,7 +35,7 @@ This 3-hop pattern works for hundreds of articles without vector search. | [[wiki/reports/_index\|reports/]] | Weekly and monthly summaries — generate: `uv run python scripts/report-generator.py --weekly` | 1 | | [[wiki/infrastructure/_index\|infrastructure/]] | Server inventory: all 10 SSH hosts — optical, optical-dev, optical-prod, baic, librechat, modocmms, box-cli, aimpress, pve | 12 | | [[wiki/testing/_index\|testing/]] | Web app testing: functional, performance, security, UI types; TDD/BDD/Agile methodologies; Selenium/Cypress/Playwright/JMeter/OWASP ZAP tools | 1 | -| [[wiki/payloadcms/_index\|payloadcms/]] | Full Payload CMS reference — getting started, config, database (Postgres/MongoDB/SQLite), all 22 field types, access control, hooks, authentication (cookies, JWT, API keys, custom strategies, token data), admin UI, custom components, Lexical rich text, live preview, versions/drafts, Local/REST/GraphQL APIs, queries, plugins, jobs queue, upload, ecommerce, production deploy, TypeScript, migration guides, i18n, localization | 68 | +| [[wiki/payloadcms/_index\|payloadcms/]] | Full Payload CMS reference — getting started, config, database (Postgres/MongoDB/SQLite), all 22 field types, access control, hooks, authentication (cookies, JWT, API keys, custom strategies, token data), admin UI, custom components, Lexical rich text, live preview, versions/drafts, Local/REST/GraphQL APIs, queries, plugins, jobs queue, upload, ecommerce, production deploy, TypeScript, migration guides, i18n, localization | 69 | | [[wiki/shared-patterns/_index\|shared-patterns/]] | Oliver Agency standard library patterns: httpx, structlog, pydantic-settings, alembic — reuse before writing from scratch | 4 | | [[wiki/mistakes/_index\|mistakes/]] | Anti-patterns extracted from sessions — per-stack running lists (fastapi, react, docker, postgres, general) — injected at session start | 5 | diff --git a/wiki/payloadcms/_index.md b/wiki/payloadcms/_index.md index 753e526..0f209ad 100644 --- a/wiki/payloadcms/_index.md +++ b/wiki/payloadcms/_index.md @@ -69,3 +69,4 @@ | [[wiki/payloadcms/fields-code\|Code Field]] | Monaco editor UI (VS Code engine) storing a plain string — language syntax highlighting, editorOptions, custom components | raw/fields__code.md | 2026-05-15 | | [[wiki/payloadcms/fields-collapsible\|Collapsible Field]] | Presentational-only layout field — groups nested fields under a collapsible header; no DB column; supports dynamic label via `({ data, path })` | raw/fields__collapsible.md | 2026-05-15 | | [[wiki/payloadcms/fields-date\|Date Field]] | Date picker field — ISO 8601 storage, pickerAppearance modes, timezone support with separate `_tz` column, custom UTC offsets, GraphQL enum names | raw/fields__date.md | 2026-05-15 | +| [[wiki/payloadcms/fields-email\|Email Field]] | Email field with built-in format validation — unique index, saveToJWT, index, placeholder, autoComplete, custom components | raw/fields__email.md | 2026-05-15 | diff --git a/wiki/payloadcms/fields-email.md b/wiki/payloadcms/fields-email.md new file mode 100644 index 0000000..b594474 --- /dev/null +++ b/wiki/payloadcms/fields-email.md @@ -0,0 +1,152 @@ +--- +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, +}) => ( + +) +``` + +### Field — Client + +```tsx +'use client' +import type { EmailFieldClientComponent } from 'payload' +import { EmailField } from '@payloadcms/ui' + +export const CustomEmailFieldClient: EmailFieldClientComponent = (props) => ( + +) +``` + +### Label — Server + +```tsx +import type { EmailFieldLabelServerComponent } from 'payload' +import { FieldLabel } from '@payloadcms/ui' + +export const CustomEmailFieldLabelServer: EmailFieldLabelServerComponent = ({ clientField, path }) => ( + +) +``` + +### Label — Client + +```tsx +'use client' +import type { EmailFieldLabelClientComponent } from 'payload' +import { FieldLabel } from '@payloadcms/ui' + +export const CustomEmailFieldLabelClient: EmailFieldLabelClientComponent = ({ field, path }) => ( + +) +``` + +## 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*