Installation

npx payload-components add collection-query

What it installs

Copies 6 source files into your project:

src/blocks/shared/PostCard.tsxshared
src/blocks/CollectionQuery/config.ts
src/blocks/CollectionQuery/Component.tsx
src/blocks/CollectionQuery/Browser.tsx
src/blocks/CollectionQuery/query.ts
src/blocks/CollectionQuery/navigation.ts

…and makes 4 edits to wire the block into your project:

Registers the block	`src/collections/Pages/index.ts`
Maps the renderer	`src/blocks/RenderBlocks.tsx`
Regenerates types	`src/payload-types.ts`
Regenerates the admin import map	`src/app/(payload)/admin/importMap.js`

Registers the blocksrc/collections/Pages/index.ts

Maps the renderersrc/blocks/RenderBlocks.tsx

Regenerates typessrc/payload-types.ts

Regenerates the admin import mapsrc/app/(payload)/admin/importMap.js

PostCard.tsx is shared source for this component family. Components that install the same path reuse that local copy, and re-running an install never overwrites a copy you have changed.

Re-running the CLI install detects existing source and wiring, then records install state in .payload-components/state.json.

Content model

The block is deliberately scoped to the official website starter's posts and categories collections.

Prop

Type

Usage

Add the block to a page. In the Payload admin, open (or create) a Page and add the CollectionQuery block to its layout.

Fill the content. Complete the fields from the content model above — the component ships sample content you can start from.

Publish. Save and publish the page; the block renders through RenderBlocks on the frontend, fully typed — no extra wiring.

Enable Pagination and Filters in the block to turn an index into a browsable archive. Changing a category resets that block to page one. Links preserve unrelated query parameters, including the state of other Collection Query blocks; browser Back/Forward restores the selection. The first 100 accessible categories, sorted by title, appear as choices. Select specific categories in the editor to curate a smaller filter bar. Manual selection preserves editor order and does not show filters or pagination.

The block renders the first page on the server. Its installed client component loads bookmarked filter/page state after hydration using a server function; no additional API route or renderer patch is needed. Interaction requires JavaScript. Loading, empty results, and retryable errors have distinct accessible states. Public reads require published posts and honor Payload access control. Draft previews require both an authenticated user and Draft Mode, and still honor access.

URLs use collection-<block-id>-page and collection-<block-id>-category; independently rendered instances without IDs use collection-<queryKey>, so give those instances unique keys.

For server-rendered bookmarked pages (including without JavaScript), pass the route's awaited searchParams through your RenderBlocks component to the block's optional searchParams prop. For a localized route, also pass the resolved Payload locale prop. For example, inside your renderer:

<CollectionQueryBlock {...block} searchParams={searchParams} locale={locale} />

The searchParams shape is Record<string, string | string[] | undefined>. If the route receives it as a Promise, await it in the route before passing it down. Without a locale prop, queries use Payload's default locale. Adapt the shared Post Card's /posts/<slug> link if your app uses a locale prefix or a different article route.

Requirements

Target: payload-website-starter
Payload: v3
Next.js: 15 / 16
shadcn UI: badge, card

Your project must already expose components.json, src/payload.config.ts — the surfaces patched by payload-components add. The CLI verifies this against the support matrix before touching anything.

Posts collection: src/collections/Posts/index.ts must match the expected starter contract. Add or restore the official Payload website starter Posts collection before installing this query block.

Posts and Categories registration: src/payload.config.ts must match the expected starter contract. The config must register Posts and Categories directly in its collections array. Import Posts and Categories and include both directly in buildConfig({ collections: [Posts, Categories, ...] }). Computed collection lists cannot be verified; expose a literal array before installing.

Categories collection: src/collections/Categories.ts or src/collections/Categories/index.ts must match the expected starter contract. Add or restore the official website starter Categories collection before installing the query block.