---
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