obsidian/raw/_processed/custom-components__list-view.md

title	label	order	desc	keywords	source
List View	List View	70		admin, components, custom, documentation, Content Management System, cms, headless, javascript, node, react, nextjs	https://payloadcms.com/docs/custom-components/list-view

The List View is where users interact with a list of Collection Documents within the Admin Panel. This is where they can view, sort, filter, and paginate their documents to find exactly what they're looking for. This is also where users can perform bulk operations on multiple documents at once, such as deleting, editing, or publishing many.

The List View can be swapped out in its entirety for a Custom View, or it can be injected with a number of Custom Components to add additional functionality or presentational elements without replacing the entire view.

**Note:** Only [Collections](../configuration/collections) have a List View. [Globals](../configuration/globals) do not have a List View as they are single documents.

Custom List View

To swap out the entire List View with a Custom View, use the admin.components.views.list property in your Collection Config:

import type { CollectionConfig } from 'payload'

export const MyCollection: CollectionConfig = {
  // ...
  admin: {
    components: {
      views: {
        // highlight-start
        list: {
          Component: '/path/to/MyCustomListView',
        },
        // highlight-end
      },
    },
  },
}

Here is an example of a custom List View:

Server Component

import React from 'react'
import type { ListViewServerProps } from 'payload'

export function MyCustomServerListView(props: ListViewServerProps) {
  return <div>This is a custom List View (Server)</div>
}

Client Component

'use client'
import React from 'react'
import type { ListViewClientProps } from 'payload'

export function MyCustomClientListView(props: ListViewClientProps) {
  return <div>This is a custom List View (Client)</div>
}

Props

Custom List Views receive a different set of props than other views because Payload pre-fetches data and pre-renders components before passing the results to your component. The exact props available depend on whether you are building a Server or Client Component.

Server Component Props (ListViewServerProps)

Server components receive all client props plus the following additional server-only data:

Prop	Description
collectionConfig	The sanitized Collection Config for this collection.
data	The paginated query result, including docs, totalDocs, page, totalPages, etc.
limit	The number of documents displayed per page.
listPreferences	Saved user preferences for this list (columns, sort, etc.).
listSearchableFields	The fields configured as searchable in the collection's admin options.
i18n	The i18n object.
locale	The active locale, if localization is enabled.
params	Route parameters from the Next.js dynamic route.
payload	The Payload class.
permissions	The current user's permissions.
searchParams	URL search parameters (page, sort, where, limit, etc.).
user	The currently authenticated user.

Client Component Props (ListViewClientProps)

Prop	Description
collectionSlug	The slug of the collection being displayed.
columnState	An array of column definitions describing the current table columns and their state.
disableBulkDelete	When true, hides the bulk delete action.
disableBulkEdit	When true, hides the bulk edit action.
disableQueryPresets	When true, disables the query presets feature.
enableRowSelections	When true, enables checkboxes on each row for bulk actions.
hasCreatePermission	Whether the current user has permission to create new documents.
hasDeletePermission	Whether the current user has permission to delete documents.
hasTrashPermission	Whether the current user has permission to use the trash.
newDocumentURL	The URL to navigate to when creating a new document.
renderedFilters	A Map<string, React.ReactNode> of pre-rendered filter components, keyed by field path.
resolvedFilterOptions	A Map<string, ResolvedFilterOptions> of resolved options for relationship filter fields.
viewType	The current view type identifier.
Table	A pre-rendered React node of the documents table. Pass this through to render the built-in table.
AfterList	Slot for components rendered after the list.
AfterListTable	Slot for components rendered after the table.
BeforeList	Slot for components rendered before the list.
BeforeListTable	Slot for components rendered before the table.
Description	Slot for the collection description component.
listMenuItems	Slot for custom items rendered in the list controls menu.

**Note:** Custom List Views are rendered inside a `ListQueryProvider`. This means any Client Component in the tree can call `useListQuery()` from `@payloadcms/ui` to read or update the current query state (search term, sort, page, filters, etc.).

Using DefaultListView

If you want to keep Payload's built-in table and controls but add your own layout around them, import and render DefaultListView from @payloadcms/ui:

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

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

Custom Components

In addition to swapping out the entire List View with a Custom View, you can also override individual components. This allows you to customize specific parts of the List View without swapping out the entire view for your own.

To override List View components for a Collection, use the admin.components property in your Collection Config:

Slot Props

All slot components (beforeList, beforeListTable, afterList, afterListTable) receive the same base set of client props plus additional server-only props in Server Components:

Client Props (BeforeListClientProps, AfterListClientProps, etc.):

Prop	Description
collectionSlug	The slug of the collection being displayed.
hasCreatePermission	Whether the current user has permission to create new documents.
hasDeletePermission	Whether the current user has permission to delete documents.
hasTrashPermission	Whether the current user has permission to use the trash.
newDocumentURL	The URL to navigate to when creating a new document.

Additional Server-Only Props (BeforeListServerProps, AfterListServerProps, etc.):

Prop	Description
collectionConfig	The sanitized Collection Config for this collection.
data	The paginated query result, including docs, totalDocs, page, totalPages, etc.
limit	The number of documents displayed per page.
listPreferences	Saved user preferences for this list (columns, sort, etc.).
listSearchableFields	The fields configured as searchable in the collection's admin options.
i18n	The i18n object.
payload	The Payload class.
permissions	The current user's permissions.
user	The currently authenticated user.

import type { CollectionConfig } from 'payload'

export const MyCollection: CollectionConfig = {
  // ...
  admin: {
    // highlight-start
    components: {
      // ...
    },
    // highlight-end
  },
}

The following options are available:

Path	Description
beforeList	An array of custom components to inject before the list of documents in the List View. More details.
beforeListTable	An array of custom components to inject before the table of documents in the List View. More details.
afterList	An array of custom components to inject after the list of documents in the List View. More details.
afterListTable	An array of custom components to inject after the table of documents in the List View. More details.
listMenuItems	An array of components to render within a menu next to the List Controls (after the Columns and Filters options)
Description	A component to render a description of the Collection. More details.

beforeList

The beforeList property allows you to inject custom components before the list of documents in the List View.

To add beforeList components, use the components.beforeList property in your Collection Config:

import type { CollectionConfig } from 'payload'

export const MyCollection: CollectionConfig = {
  // ...
  admin: {
    components: {
      // highlight-start
      beforeList: ['/path/to/MyBeforeListComponent'],
      // highlight-end
    },
  },
}

Here's an example of a custom beforeList component:

Server Component

import React from 'react'
import type { BeforeListServerProps } from 'payload'

export function MyBeforeListComponent(props: BeforeListServerProps) {
  return <div>This is a custom beforeList component (Server)</div>
}

Client Component

'use client'
import React from 'react'
import type { BeforeListClientProps } from 'payload'

export function MyBeforeListComponent(props: BeforeListClientProps) {
  return <div>This is a custom beforeList component (Client)</div>
}

beforeListTable

The beforeListTable property allows you to inject custom components before the table of documents in the List View.

To add beforeListTable components, use the components.beforeListTable property in your Collection Config:

import type { CollectionConfig } from 'payload'

export const MyCollection: CollectionConfig = {
  // ...
  admin: {
    components: {
      // highlight-start
      beforeListTable: ['/path/to/MyBeforeListTableComponent'],
      // highlight-end
    },
  },
}

Here's an example of a custom beforeListTable component:

Server Component

import React from 'react'
import type { BeforeListTableServerProps } from 'payload'

export function MyBeforeListTableComponent(props: BeforeListTableServerProps) {
  return <div>This is a custom beforeListTable component (Server)</div>
}

Client Component

'use client'
import React from 'react'
import type { BeforeListTableClientProps } from 'payload'

export function MyBeforeListTableComponent(props: BeforeListTableClientProps) {
  return <div>This is a custom beforeListTable component (Client)</div>
}

afterList

The afterList property allows you to inject custom components after the list of documents in the List View.

To add afterList components, use the components.afterList property in your Collection Config:

import type { CollectionConfig } from 'payload'

export const MyCollection: CollectionConfig = {
  // ...
  admin: {
    components: {
      // highlight-start
      afterList: ['/path/to/MyAfterListComponent'],
      // highlight-end
    },
  },
}

Here's an example of a custom afterList component:

Server Component

import React from 'react'
import type { AfterListServerProps } from 'payload'

export function MyAfterListComponent(props: AfterListServerProps) {
  return <div>This is a custom afterList component (Server)</div>
}

Client Component

'use client'
import React from 'react'
import type { AfterListClientProps } from 'payload'

export function MyAfterListComponent(props: AfterListClientProps) {
  return <div>This is a custom afterList component (Client)</div>
}

afterListTable

The afterListTable property allows you to inject custom components after the table of documents in the List View.

To add afterListTable components, use the components.afterListTable property in your Collection Config:

import type { CollectionConfig } from 'payload'

export const MyCollection: CollectionConfig = {
  // ...
  admin: {
    components: {
      // highlight-start
      afterListTable: ['/path/to/MyAfterListTableComponent'],
      // highlight-end
    },
  },
}

Here's an example of a custom afterListTable component:

Server Component

import React from 'react'
import type { AfterListTableServerProps } from 'payload'

export function MyAfterListTableComponent(props: AfterListTableServerProps) {
  return <div>This is a custom afterListTable component (Server)</div>
}

Client Component

'use client'
import React from 'react'
import type { AfterListTableClientProps } from 'payload'

export function MyAfterListTableComponent(props: AfterListTableClientProps) {
  return <div>This is a custom afterListTable component (Client)</div>
}

Description

The Description property allows you to render a custom description of the Collection in the List View.

To add a Description component, use the components.Description property in your Collection Config:

import type { CollectionConfig } from 'payload'

export const MyCollection: CollectionConfig = {
  // ...
  admin: {
    components: {
      // highlight-start
      Description: '/path/to/MyDescriptionComponent',
      // highlight-end
    },
  },
}

**Note:** The `Description` component is shared between the List View and the [Edit View](./edit-view).

Here's an example of a custom Description component:

Server Component

import React from 'react'
import type { ViewDescriptionServerProps } from 'payload'

export function MyDescriptionComponent(props: ViewDescriptionServerProps) {
  return <div>This is a custom Collection description component (Server)</div>
}

Client Component

'use client'
import React from 'react'
import type { ViewDescriptionClientProps } from 'payload'

export function MyDescriptionComponent(props: ViewDescriptionClientProps) {
  return <div>This is a custom Collection description component (Client)</div>
}