obsidian/wiki/payloadcms/document-views.md

title	aliases	tags	sources	created	updated
Document Views	document-views payload-document-tabs payload-edit-view-config	payloadcms admin custom-components views tabs	raw/custom-components__document-views.md	2026-05-15	2026-05-15

Overview

Document Views are the set of views that together represent a single wiki/payloadcms/collection-config or wiki/payloadcms/globals-config 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

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

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:

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:

'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
• See wiki/payloadcms/custom-components for the full slot system

---

Sources

• raw/custom-components__document-views.md
• https://payloadcms.com/docs/custom-components/document-views