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.

<Banner type="info"> **Note:** Only [Collections](../configuration/collections) have a List View. [Globals](../configuration/globals) do not have a List View as they are single documents. </Banner>

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

tsx

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

tsx

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

<Banner type="info"> **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.). </Banner>

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:

tsx

'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

tsx

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

tsx

'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

tsx

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

tsx

'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

tsx

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

tsx

'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

tsx

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

tsx

'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
    },
  },
}

<Banner type="warning"> **Note:** The `Description` component is shared between the List View and the [Edit View](./edit-view). </Banner>

Here's an example of a custom Description component:

Server Component

tsx

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

tsx

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

Custom List View

Server Component

Client Component

Props

Server Component Props (ListViewServerProps)

Client Component Props (ListViewClientProps)

Using DefaultListView

Custom Components

Slot Props

beforeList

Server Component

Client Component

beforeListTable

Server Component

Client Component

afterList

Server Component

Client Component

afterListTable

Server Component

Client Component

Description

Server Component

Client Component

Server Component Props (`ListViewServerProps`)

Client Component Props (`ListViewClientProps`)