obsidian/wiki/payloadcms/custom-components-list-view.md

title	aliases	tags	sources	created	updated
Custom Components — List View	list-view-custom-components payload-list-view collection-list-view	payloadcms admin custom-components react collections	raw/custom-components__list-view.md	2026-05-15	2026-05-15

Overview

The List View is the Admin Panel page where users browse, sort, filter, and paginate a wiki/payloadcms/collection-config documents. It also supports bulk operations (delete, edit, publish).

Only Collections have a List View. Globals do not — they are single documents.

Two customization approaches:

1. Replace the entire view with a Custom View
2. Inject components into specific slots without replacing the whole view

---

Replacing the Entire List View

Set admin.components.views.list.Component in wiki/payloadcms/collection-config:

import type { CollectionConfig } from 'payload'

export const MyCollection: CollectionConfig = {
  admin: {
    components: {
      views: {
        list: {
          Component: '/path/to/MyCustomListView',
        },
      },
    },
  },
}

Server Component Props (ListViewServerProps)

Prop	Description
collectionConfig	Sanitized Collection Config
data	Paginated result: docs, totalDocs, page, totalPages
limit	Documents per page
listPreferences	Saved user preferences (columns, sort)
listSearchableFields	Fields configured as searchable
i18n	i18n object
locale	Active locale (if localization enabled)
params	Next.js route params
payload	Payload class instance
permissions	Current user permissions
searchParams	URL search params (page, sort, where, limit)
user	Currently authenticated user

Client Component Props (ListViewClientProps)

Prop	Description
collectionSlug	Collection slug
columnState	Current table column definitions
disableBulkDelete / disableBulkEdit	Hide bulk actions
disableQueryPresets	Disable query presets feature
enableRowSelections	Enable checkboxes for bulk actions
hasCreatePermission / hasDeletePermission / hasTrashPermission	User permission flags
newDocumentURL	URL for creating new documents
renderedFilters	Map<string, React.ReactNode> of pre-rendered filter components
resolvedFilterOptions	Map<string, ResolvedFilterOptions> for relationship filters
viewType	Current view type identifier
Table	Pre-rendered built-in documents table — pass through to keep it
AfterList / AfterListTable / BeforeList / BeforeListTable	Slot nodes
Description	Collection description slot
listMenuItems	Slot for custom list controls menu items

Using DefaultListView

Wrap the built-in table without replacing it:

'use client'
import { DefaultListView } from '@payloadcms/ui'
import type { ListViewClientProps } from 'payload'

export function MyCustomClientListView(props: ListViewClientProps) {
  return (
    <div>
      <h1>My Custom Header</h1>
      <DefaultListView {...props} />
    </div>
  )
}

useListQuery Hook

Any Client Component inside a custom List View can call useListQuery() from @payloadcms/ui to read or mutate the current query state (search term, sort, page, filters). The view is wrapped in ListQueryProvider automatically.

---

Slot Components (Partial Customization)

Instead of replacing the whole view, inject components at specific positions via admin.components:

Config Key	Position
beforeList	Before the entire list
beforeListTable	Before the documents table
afterList	After the entire list
afterListTable	After the documents table
listMenuItems	In the list controls menu (next to Columns/Filters)
Description	Collection description (shared with [[wiki/payloadcms/custom-components-edit-view

admin: {
  components: {
    beforeList: ['/path/to/MyBeforeListComponent'],
    beforeListTable: ['/path/to/MyBeforeListTableComponent'],
    afterList: ['/path/to/MyAfterListComponent'],
    afterListTable: ['/path/to/MyAfterListTableComponent'],
    listMenuItems: ['/path/to/MyMenuItem'],
    Description: '/path/to/MyDescriptionComponent',
  },
}

Slot Component Props

Client Props (BeforeListClientProps, AfterListClientProps, etc.):

Prop	Description
collectionSlug	Collection slug
hasCreatePermission / hasDeletePermission / hasTrashPermission	Permission flags
newDocumentURL	URL for creating new documents

Additional Server-Only Props:

Prop	Description
collectionConfig	Sanitized Collection Config
data	Paginated result
limit	Documents per page
listPreferences	Saved user preferences
listSearchableFields	Searchable fields config
i18n	i18n object
payload	Payload class instance
permissions	Current user permissions
user	Authenticated user

Description Note

Description is shared between List View and wiki/payloadcms/custom-components-edit-view — one component serves both contexts.

---

Key Takeaways

• Only Collections have a List View; Globals don't
• Two strategies: replace entire view (views.list.Component) or inject slots (beforeList, afterList, etc.)
• Server Components get full server-side data (collectionConfig, data, payload); Client Components get UI state and pre-rendered nodes
• Table prop in ListViewClientProps is the pre-rendered table — pass it through in DefaultListView or render manually to keep built-in functionality
• useListQuery() from @payloadcms/ui lets any child Client Component read/update query state
• Description component is shared with the Edit View — changes affect both views
• listMenuItems adds entries to the list controls menu alongside built-in Columns/Filters

---

Related

• wiki/payloadcms/custom-views — replacing views at root/collection/global scope
• wiki/payloadcms/custom-components-edit-view — Edit View slots and controls
• wiki/payloadcms/document-views — Document View keys and tab config
• wiki/payloadcms/collection-config — full collection configuration reference
• wiki/payloadcms/react-hooks — useListQuery and other @payloadcms/ui hooks