67 lines
2.6 KiB
Markdown
67 lines
2.6 KiB
Markdown
---
|
|
title: "UI Field"
|
|
aliases: [ui-field, presentational-field, payload-ui-field]
|
|
tags: [payloadcms, fields, admin-panel, react, components]
|
|
sources: [raw/fields__ui.md]
|
|
created: 2026-05-15
|
|
updated: 2026-05-15
|
|
---
|
|
|
|
## Overview
|
|
|
|
The UI field is **presentational-only** — it stores no data and has no effect on documents. It lets you inject arbitrary React components directly into the Admin Panel, nested among your other fields.
|
|
|
|
```ts
|
|
import type { Field } from 'payload'
|
|
|
|
export const MyUIField: Field = {
|
|
name: 'myCustomUIField',
|
|
type: 'ui',
|
|
admin: {
|
|
components: {
|
|
Field: '/path/to/MyCustomUIField',
|
|
Cell: '/path/to/MyCustomUICell',
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
## Config Options
|
|
|
|
| Option | Required | Description |
|
|
|--------|----------|-------------|
|
|
| `name` | ✅ | Unique identifier for this field |
|
|
| `label` | — | Human-readable label |
|
|
| `admin.components.Field` | ✅ | React component rendered in Edit View |
|
|
| `admin.components.Cell` | — | React component rendered in List View cells |
|
|
| `admin.disabled` | — | `true` to disable everywhere, or granular `{ field?, column?, filter?, groupBy?, bulkEdit? }` |
|
|
| `custom` | — | Extension point for plugin data |
|
|
|
|
> **Default:** UI fields have `disabled: { bulkEdit: true }` by default.
|
|
|
|
## Use Cases
|
|
|
|
- **Descriptive text** — add context/instructions between fields in Edit View
|
|
- **Action buttons** — "Refund" button in Order sidebar, "Clear Cache" button, "View Page" shortcut
|
|
- **Custom controls** — any React component injected exactly where editors need it
|
|
|
|
## Key Takeaways
|
|
|
|
- UI field has **zero impact on stored data** — purely admin UI enhancement
|
|
- `admin.components.Field` is required (the component to render)
|
|
- `admin.components.Cell` renders in List View columns — optional
|
|
- Bulk edit is disabled by default (no data to edit)
|
|
- Can trigger `fetch` calls, external APIs, or side effects from within the Admin Panel
|
|
- Use [[wiki/payloadcms/fields-overview|Fields Overview]] `admin.condition` to show/hide based on other field values
|
|
|
|
## Related
|
|
|
|
- [[wiki/payloadcms/fields-overview|Fields Overview]] — cross-cutting field config, `admin.components` pattern
|
|
- [[wiki/payloadcms/custom-components-authoring|Custom Components — Authoring Guide]] — how to write RSC vs Client components, Import Map
|
|
- [[wiki/payloadcms/fields-row|Row Field]] — another presentational-only layout field (horizontal grouping)
|
|
- [[wiki/payloadcms/fields-collapsible|Collapsible Field]] — presentational layout with collapsible header
|
|
- [[wiki/payloadcms/admin-panel-overview|Admin Panel Overview]] — Edit View and List View structure
|
|
|
|
## Sources
|
|
|
|
- `raw/fields__ui.md` — https://payloadcms.com/docs/fields/ui
|