133 lines
4.3 KiB
Markdown
133 lines
4.3 KiB
Markdown
---
|
|
title: "Document Views"
|
|
aliases: [document-views, payload-document-tabs, payload-edit-view-config]
|
|
tags: [payloadcms, admin, custom-components, views, tabs]
|
|
sources: [raw/custom-components__document-views.md]
|
|
created: 2026-05-15
|
|
updated: 2026-05-15
|
|
---
|
|
|
|
## Overview
|
|
|
|
Document Views are the set of views that together represent a single [[wiki/payloadcms/collection-config|Collection]] or [[wiki/payloadcms/globals-config|Global]] document in the Payload admin panel. All Document Views live under `/collections/:collectionSlug/:id` or `/globals/:globalSlug`.
|
|
|
|
Customized via `admin.components.views.edit[key]` in Collection or Global config.
|
|
|
|
---
|
|
|
|
## Built-in View Keys
|
|
|
|
| Key | Description | Tab label |
|
|
|---------------|-------------------------------------------------------------------|-----------------|
|
|
| `root` | Overrides the **entire** document layout (no controls, no tabs) | — |
|
|
| `default` | Primary edit view — where content is edited | "Edit" |
|
|
| `versions` | Version history list | "Versions" |
|
|
| `version` | Single version view | "Version" |
|
|
| `api` | REST API JSON response for the document | "API" |
|
|
| `livePreview` | Live Preview interface | "Live Preview" |
|
|
| `[key]` | Any custom key → adds a new Document View | custom tab |
|
|
|
|
---
|
|
|
|
## Config Pattern
|
|
|
|
```ts
|
|
import type { CollectionConfig } from 'payload'
|
|
|
|
export const MyCollection: CollectionConfig = {
|
|
slug: 'my-collection',
|
|
admin: {
|
|
components: {
|
|
views: {
|
|
edit: {
|
|
default: {
|
|
Component: '/path/to/MyCustomEditView',
|
|
},
|
|
myCustomView: {
|
|
Component: '/path/to/MyCustomView',
|
|
path: '/my-custom-tab',
|
|
tab: {
|
|
label: 'My Tab',
|
|
href: '/my-custom-tab',
|
|
order: '100',
|
|
},
|
|
},
|
|
},
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Document Root
|
|
|
|
- Mounted at the top-level document route
|
|
- **Completely replaces** the document layout: no title, no tabs, no nested views
|
|
- You must render all controls yourself
|
|
- Use `edit.default` instead if you only want to replace the Edit View
|
|
|
|
```ts
|
|
edit: {
|
|
root: {
|
|
Component: '/path/to/MyCustomRootComponent',
|
|
},
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Document Tabs
|
|
|
|
Each Document View can expose a navigation tab. Tab options:
|
|
|
|
| Property | Description |
|
|
|-------------|------------------------------------------------------------------|
|
|
| `label` | Display label in the tab bar |
|
|
| `href` | URL when clicked (defaults to the view's `path`) |
|
|
| `order` | Numeric order in the tab bar; works on built-in and custom tabs |
|
|
| `Component` | Replace the entire tab with a custom Server or Client component |
|
|
|
|
### Custom Tab Component Examples
|
|
|
|
**Server Component:**
|
|
```tsx
|
|
import type { DocumentTabServerProps } from 'payload'
|
|
import { Link } from '@payloadcms/ui'
|
|
|
|
export function MyTab(props: DocumentTabServerProps) {
|
|
return <Link href="/my-custom-tab">Custom Tab (Server)</Link>
|
|
}
|
|
```
|
|
|
|
**Client Component:**
|
|
```tsx
|
|
'use client'
|
|
import type { DocumentTabClientProps } from 'payload'
|
|
import { Link } from '@payloadcms/ui'
|
|
|
|
export function MyTab(props: DocumentTabClientProps) {
|
|
return <Link href="/my-custom-tab">Custom Tab (Client)</Link>
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Key Takeaways
|
|
|
|
- All document views share the same layout; tabs are optional per view
|
|
- `root` key = nuclear option: takes over everything, no built-in controls rendered
|
|
- `default` key = safe replacement of just the Edit view (tabs/controls remain)
|
|
- Custom views use `[key]: { Component, path, tab }` pattern
|
|
- Tab `order` works on both built-in and custom tabs — use it to control position
|
|
- Applies equally to Collections and Globals
|
|
- For building the view components themselves, see [[wiki/payloadcms/custom-views|Custom Views]]
|
|
- See [[wiki/payloadcms/custom-components|Custom Components]] for the full slot system
|
|
|
|
---
|
|
|
|
## Sources
|
|
|
|
- `raw/custom-components__document-views.md`
|
|
- https://payloadcms.com/docs/custom-components/document-views
|