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

## Overview

The List View is the Admin Panel page where users browse, sort, filter, and paginate a [[wiki/payloadcms/collection-config|Collection's]] 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|Collection Config]]:

```ts
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:

```tsx
'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|Edit View]]) |

```ts
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|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|Custom Views]] — replacing views at root/collection/global scope
- [[wiki/payloadcms/custom-components-edit-view|Custom Components — Edit View]] — Edit View slots and controls
- [[wiki/payloadcms/document-views|Document Views]] — Document View keys and tab config
- [[wiki/payloadcms/collection-config|Collection Config]] — full collection configuration reference
- [[wiki/payloadcms/react-hooks|React Hooks]] — `useListQuery` and other `@payloadcms/ui` hooks
