diff --git a/raw/fields__select.md b/raw/_processed/fields__select.md similarity index 100% rename from raw/fields__select.md rename to raw/_processed/fields__select.md diff --git a/wiki/_master-index.md b/wiki/_master-index.md index f9310dc..af1d614 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 | 79 | +| [[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 | 80 | | [[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 91f1d1f..05b6404 100644 --- a/wiki/payloadcms/_index.md +++ b/wiki/payloadcms/_index.md @@ -80,3 +80,4 @@ | [[wiki/payloadcms/fields-relationship\|Relationship Field]] | Link documents across collections — has-one/has-many, polymorphic (`{ relationTo, value }`), filterOptions, bi-directional via Join, depth auto-populate | raw/fields__relationship.md | 2026-05-15 | | [[wiki/payloadcms/fields-rich-text\|Rich Text Field]] | WYSIWYG field stored as JSON, Lexical-powered, `editor` option for full customization, virtual/hidden/localized support | raw/fields__rich-text.md | 2026-05-15 | | [[wiki/payloadcms/fields-row\|Row Field]] | Presentational-only layout field — arranges nested fields horizontally; no DB column; width via `admin.width` on children | raw/fields__row.md | 2026-05-15 | +| [[wiki/payloadcms/fields-select\|Select Field]] | Dropdown / multi-select enum field — options, hasMany, filterOptions (role-based/dependent), Postgres enumName/dbName, isSortable | raw/fields__select.md | 2026-05-15 | diff --git a/wiki/payloadcms/fields-select.md b/wiki/payloadcms/fields-select.md new file mode 100644 index 0000000..d614722 --- /dev/null +++ b/wiki/payloadcms/fields-select.md @@ -0,0 +1,156 @@ +--- +title: "Select Field" +aliases: [select-field, multi-select, dropdown-field] +tags: [payloadcms, fields, select, enum, dropdown] +sources: [raw/fields__select.md] +created: 2026-05-15 +updated: 2026-05-15 +--- + +Dropdown-style field storing one or many values from a predefined list. Backed by a database enum (Postgres) or string field. + +## Basic Config + +```ts +import type { Field } from 'payload' + +export const MySelectField: Field = { + name: 'status', + type: 'select', + options: [ + { label: 'Draft', value: 'draft' }, + { label: 'Published', value: 'published' }, + { label: 'Archived', value: 'archived' }, + ], +} +``` + +## Config Options + +| Option | Required | Description | +|--------|----------|-------------| +| `name` | ✓ | DB property name | +| `options` | ✓ | Array of strings or `{ label, value }` objects | +| `hasMany` | | `true` → allows multiple selections (stored as array) | +| `filterOptions` | | Dynamically filter visible/saveable options | +| `enumName` | | Custom Postgres enum name (auto-generated if omitted) | +| `dbName` | | Custom join table name when `hasMany: true` (Postgres) | +| `unique` | | DB-level unique constraint | +| `index` | | Add index for faster queries | +| `localized` | | Per-locale values | +| `saveToJWT` | | Include value in auth JWT | +| `defaultValue` | | Default option value | +| `required` | | Require a selection | +| `hidden` | | Exclude from all APIs (still stored in DB) | +| `virtual` | | Disable DB storage, or link to relationship | +| `interfaceName` | | Reusable TS interface + GraphQL type | +| `typescriptSchema` | | Override TS type generation with JSON schema | + +> **GraphQL constraint:** option values must not contain hyphens or special characters — only underscores allowed. Values with special characters are reformatted automatically for GraphQL enums. + +## hasMany — Multi-Select + +```ts +{ + name: 'selectedFeatures', + type: 'select', + hasMany: true, + admin: { + isClearable: true, + isSortable: true, // drag-and-drop reordering + }, + options: [ + { label: 'Metallic Paint', value: 'metallic_paint' }, + { label: 'Alloy Wheels', value: 'alloy_wheels' }, + { label: 'Carbon Fiber Dashboard', value: 'carbon_fiber_dashboard' }, + ], +} +``` + +- `hasMany: true` stores an array of values +- `isSortable` only works when `hasMany: true` +- Postgres creates a separate join table (`dbName` to override its name) + +## filterOptions + +Dynamically filters which options appear in the Admin UI **and** which can be saved: + +```ts +{ + type: 'select', + options: [ + { label: 'One', value: 'one' }, + { label: 'Two', value: 'two' }, + { label: 'Three', value: 'three' }, + ], + filterOptions: ({ options, data }) => + data.disallowOption1 + ? options.filter(o => (typeof o === 'string' ? o : o.value) !== 'one') + : options, +} +``` + +Use cases: +- Admin-only options based on `req.user.role` +- Dependent dropdowns (city filtered by selected state) + +> Unlike `filterOptions` on [[wiki/payloadcms/fields-relationship|Relationship]] / [[wiki/payloadcms/fields-overview|Upload]] fields, the return value here is an **array of options**, not a query constraint. + +## Admin Options + +| Property | Description | +|----------|-------------| +| `isClearable` | Show a clear/reset button in the UI | +| `isSortable` | Enable drag-and-drop reordering (requires `hasMany: true`) | +| `placeholder` | Custom placeholder text or function | + +## Custom Components + +### Server Component (Field) + +```tsx +import type { SelectFieldServerComponent } from 'payload' +import { SelectField } from '@payloadcms/ui' + +export const CustomSelectFieldServer: SelectFieldServerComponent = ({ + clientField, path, schemaPath, permissions, +}) => ( + +) +``` + +### Client Component (Field) + +```tsx +'use client' +import type { SelectFieldClientComponent } from 'payload' +import { SelectField } from '@payloadcms/ui' + +export const CustomSelectFieldClient: SelectFieldClientComponent = (props) => ( + +) +``` + +### Label Components + +Use `FieldLabel` from `@payloadcms/ui` for both server and client label overrides — pass `label`, `path`, and `required` from `clientField`/`field`. + +## Key Takeaways + +- `options` values must use underscores, not hyphens (GraphQL enum constraint) +- `hasMany: true` switches storage to an array; Postgres creates a join table +- `filterOptions` controls both UI display and what values can be saved — useful for role-based or dependent dropdowns +- `enumName` / `dbName` let you control Postgres schema naming explicitly +- `isSortable` drag-and-drop only activates when `hasMany: true` +- Use `interfaceName` to generate a reusable TypeScript interface and GraphQL type for this field's enum + +## Related + +- [[wiki/payloadcms/fields-radio|Radio Field]] — single-choice alternative with radio-button UI +- [[wiki/payloadcms/fields-relationship|Relationship Field]] — link to other documents (also has `filterOptions`) +- [[wiki/payloadcms/fields-overview|Fields Overview]] — shared field config, validation, admin options +- [[wiki/payloadcms/database-postgres|Database — Postgres]] — enum and join table generation details + +## Sources + +- `raw/fields__select.md` — https://payloadcms.com/docs/fields/select