A dedicated search collection to optimize queries.
Cross-collection searching with priority sorting.
Improved performance compared to default like-queries.
Support for relationship fields, making related data (e.g., author names) searchable.

Understanding search in Payload

There are two primary ways to implement search in Payload:

Default Like-Query Search (Built-in)

Works by performing a RegExp query on specified fields. Uses listSearchableFields in a collection’s config. Works well for small datasets, but slows down with large collections

Payload Search Plugin (Recommended)

More performant. Creates a separate search collection for indexed documents. Allows custom field selection to improve search accuracy. Enables cross-collection searching and priority sorting. Stores relationship fields (e.g., author names), making them searchable

Note: While third-party search alternatives are useful, they require additional setup and maintenance. The Payload Search Plugin offers a built-in solution without external dependencies.

Setting up a custom admin search component

Before we implement the actual search logic, we’ll scaffold a minimal component that appears in the Payload admin. This lets us display search results inside the admin UI — without modifying Payload’s built-in dashboard.

Create a new file at src/components/BeforeDashboard.tsx.

We’ll fill this in later, but for now, just register it in your Payload config:

1admin: {
2  components: {
3    beforeDashboard: [BeforeDashboard],
4  },
5},

Make sure you import the component:

1import BeforeDashboard from './components/BeforeDashboard';

Once that's wired up, you’ll see your custom UI render above the default dashboard in the Payload admin.

We'll come back and build out this component after setting up the plugin.

Installing the Payload Search Plugin

First, install the official search plugin: pnpm add @payloadcms/plugin-search

Next, open your Payload config (payload.config.ts) and register the plugin:

1import { searchPlugin } from '@payloadcms/plugin-search';
2
3export default buildConfig({
4  plugins: [
5    searchPlugin({
6      collections: ['blogArticles', 'authors'],
7    }),
8  ],
9});

This configuration: Enables search for blogArticles and authors. Creates a new search collection (searchResults). Now, restart the development server: pnpm dev

Once the Payload Admin Panel reloads, you should see a new "Search Results" collection.

Indexing Data for Search

By default, the search collection will be empty. To populate it, we need to index existing data.

Manually Reindexing

Payload provides a Reindex button in the Admin Panel.

Go to Search Results in the Admin Panel.
Click "Reindex" button and then "All Collections" to populate the search collection.

Any new blog articles or authors added after this will be indexed automatically.

Customizing Search Fields

By default, the search plugin only stores the title. We can improve search accuracy by adding custom fields.

1. Adding a "Description" Field

Modify the plugin config to include a description field:

1searchPlugin({
collections: ['blogArticles', 'authors'],
searchOverrides: {
  fields: (defaultFields) => [
    ...defaultFields,
    {
      name: 'description',
      type: 'text',
      label: 'Description',
      admin: { readOnly: true },
    },
  ],
},
14});

This ensures each search entry stores a description.

2. Prepare the data for search

Payload uses Lexical for rich text, which stores content in a deeply nested JSON structure. That’s not searchable by default.

To make it searchable, we flatten that content into plain text using a utility function.

We do this inside the beforeSync hook, which gives us full control over what gets indexed.

In this hook, we extract and map rich text and relationship fields into unified title and description fields for better search results.

But first, we'll need to create a utility function into utils/extractPlaintText.ts.

1const extractTextFromNode = (node: any): string => {
if (!node || typeof node !== 'object') {
return ''
}
5
// Extract text from text nodes
if (node.type === 'text' && node.text) {
return node.text
}
10
// Recursively extract text from child nodes
if (Array.isArray(node.children)) {
return node.children
	.map((child: any) => extractTextFromNode(child))
	.join(' ')
	.replace(/\s+/g, ' ') // Replace multiple spaces with a single space
	.trim()
}
19
// Fallback for other node types
return ''
22}
23
24export const extractPlainText = (content: any): string => {
if (!content || typeof content !== 'object') {
// If the content is not an object, return an empty string
return ''
}
29
// Check if the content is in Lexical's serialized editor state format
if (content.root && Array.isArray(content.root.children)) {
// Traverse the children of the root node
return content.root.children
	.map((child: any) => extractTextFromNode(child))
	.join(' ')
	.replace(/\s+/g, ' ') // Replace multiple spaces with a single space
	.trim()
}
39
// Fallback for other formats
return ''
42}

And be sure to import that into your Payload config: import { extractPlainText } from './utils/extractPlainText';

Next, we'll define the beforeSync hook:

1searchPlugin({
2
collections: ['blog-articles', 'blog-authors'],
4
searchOverrides: {
  fields: ({ defaultFields }) => [
    ...defaultFields,
    {
      name: 'description',
      type: 'textarea',
      label: 'Description',
      admin: {
        readOnly: true,
      },
    },
  ],
17
  // Map content from your original documents into the shape expected in the search index
  beforeSync: ({ originalDoc, searchDoc }) => {
    const collection = searchDoc.doc.relationTo;
21
    // If the document is from the blog-articles collection...
    if (collection === 'blog-articles') {
      return {
        ...searchDoc,
        // Map the 'heading' field from the article as the search result title
        title: originalDoc.heading,
28
        // Extract and flatten the rich text content to make it searchable
        description: extractPlainText(originalDoc.content),
      };
    }
33
    // If the document is from the blog-authors collection...
    if (collection === 'blog-authors') {
      return {
        ...searchDoc,
        // Use the author's name as the title
        title: originalDoc.name,
40
        // Extract plain text from the bio for consistent searching
        description: extractPlainText(originalDoc.bio),
      };
    }
45
    // For any other collections not explicitly handled, fall back to the default
    return searchDoc;
  },
},
50}),

This ensures:

Blog articles store heading as the title and content as the description.
Authors store name as the title and bio as the description.

Return to the admin panel and reindex all the collections—you should see we have the title as either the author name or blog title, and the description field will have the content of either the author profile or blog article.

3. Building the search admin UI

Now that indexing is set up, we’ll return to the BeforeDashboard.tsx component we registered earlier and implement the actual search logic.

Next, we'll build a custom search input that queries the unified search collection created by the plugin. It performs a like search on both title and description, then displays results in a dropdown that links directly to the related documents in the Payload admin.

1'use client'
2
3import { SelectInput } from '@payloadcms/ui'
4import React, { useEffect } from 'react'
5import qs from 'qs'
6
7// Custom debounce hook
8function useDebounce(value: string, delay: number) {
const [debouncedValue, setDebouncedValue] = React.useState(value)
10
useEffect(() => {
  const timer = setTimeout(() => {
    setDebouncedValue(value)
  }, delay)
15
  return () => {
    clearTimeout(timer)
  }
}, [value, delay])
20
return debouncedValue
22}
23
24export default function BeforeDashboard() {
const [searchResults, setSearchResults] = React.useState({ docs: [] })
const [searchTerm, setSearchTerm] = React.useState('')
const debouncedSearchTerm = useDebounce(searchTerm, 500)
28
// Effect to trigger search when debounced value changes
useEffect(() => {
  if (debouncedSearchTerm) {
    searchDocs(debouncedSearchTerm)
  } else {
    setSearchResults({ docs: [] })
  }
}, [debouncedSearchTerm]) // Added initialSearchResults to dependencies
37
async function searchDocs(search: string) {
  const queryObj = {
    where: {
      or: [
        {
          title: {
            like: search,
          },
        },
        {
          description: {
            like: search,
          },
        },
      ],
    },
  }
  const response = await fetch(`/api/search?${qs.stringify(queryObj)}`)
  const data = await response.json()
57
  setSearchResults(data)
}
60
return (
  <div>
    <SelectInput
      onInputChange={(value) => {
        setSearchTerm(value)
      }}
      onChange={(value: any) => {
        // Open new tab with participant
        window.open(`/admin/collections/search/${value.value}`, '_blank')
      }}
      options={searchResults.docs.map((res: any) => ({
        label: `${res.title} - ${res.description} | ${res.doc.relationTo}`,
        value: res.id,
      }))}
      className=""
      label=""
      name="search"
      path="search"
    />
  </div>
)
82}

Final thoughts

By implementing the Payload Search Plugin, we:

Improved search performance
Enabled search across multiple collections
Made relationship fields searchable
Optimized search for rich text and date fields
Created a unified search experience