Related Posts
A compact end-of-post list of related articles your template selects; the current post is always excluded.
v0.1.0Post componentpayload-website-starter
import React, { type ReactNode, useId } from 'react'
export type RelatedPost = {
title: string
/** A site path such as /posts/slug, or an HTTP(S) URL. Other values are skipped. */
href: string
excerpt?: string | null
/** Pass your populated Payload Media or Next Image element, with meaningful alt text. */Installation
npx payload-components add related-postsnpx shadcn@latest add https://www.payload-components.xyz/r/related-posts.jsonThis file-only component needs no Payload wiring: either command copies the same source files.
Usage
Import RelatedPosts into your post template and pass public content as props. The install adds no admin fields, so your template decides what loads and when it publishes.
Props your template passes
Props- Title
- Related posts
- Current Href
- /posts/build-for-the-people-who-publish
- Posts
- 01Write the brief before the blockEditors know what a page needs to say. Start there, then decide which fields the block deserves.
- 02Drafts are a feature, not a statePreview, review, and schedule changes without a second CMS or a staging copy of the site.
- 03Fewer fields, better pagesEvery optional field is a decision you hand to an editor. Make fewer of them, and make them count.
- 01
import { RelatedPosts } from '@/components/RelatedPosts/Component'
import { Media } from '@/components/Media'
import type { Post } from '@/payload-types'
// Render once at the end of your post template, after the article body.
export function ArticleRelatedPosts({ post }: { post: Post }) {
return (
<RelatedPosts
currentHref={`/posts/${post.slug}`}
posts={(post.relatedPosts ?? []).flatMap((related) =>
typeof related === 'object' && related?.slug
? [
{
title: related.title,
href: `/posts/${related.slug}`,
excerpt: related.meta?.description,
publishedAt: related.publishedAt,
image:
related.meta?.image && typeof related.meta.image === 'object' ? (
<Media resource={related.meta.image} />
) : undefined,
},
]
: [],
)}
/>
)
}Place it once per post, after the article body and any author card. It renders a section labelled by its h2, with an h3 per post, so the page keeps the single h1 from your post header. When no posts remain after the current post, unsafe hrefs, and repeats are removed, it renders nothing, so the template needs no empty check. The Payload website starter ships its own RelatedPosts in @/blocks/RelatedPosts/Component. This install leaves that file alone, so swap the import in your post page or alias one of the two.
Selection stays in your template. The example reads the starter's manually curated relatedPosts relationship, which its post query populates at depth: 2. Automatic recommendations, such as recent posts that share a category, belong in a separate query that passes its results through the same posts prop. This component never queries, ranks, or fills the list.
Content model
These are React props supplied by your post template. This component adds no collection fields and does not query, rank, or recommend content: your template selects the posts and passes them in display order. Resolve relationship IDs before supplying public display data.
Prop
Type
Each entry in posts carries:
Prop
Type
What it installs
Composition
How the component sits in your template
Your template<RelatedPosts />titlecurrentHrefposts[]titlehrefexcerptpublishedAt
- Props
src/components/RelatedPosts/Component.tsx
Files
Copies 1 file into your project.
Edits
Nothing is registered or generated. This file-only component is composed in your template, not added through the admin.
Re-running the install detects existing source and wiring, then records install state in .payload-components/state.json.
Requirements
- Target
- payload-website-starter, payload-blocks-app
- Payload
- v3 (3.25 or newer) / v4 (experimental)
- Next.js
- 15 / 16 with v316 (16.4 or newer) with v4
- shadcn UI
- None
Payload v4 support is experimental: it needs Next.js 16 (16.4 or newer) and Node.js 24.22.1 or newer. Payload v3 (3.25 or newer) stays fully supported.
Direct shadcn installation needs React 19 and Tailwind with your theme tokens; this component has no Payload runtime imports. The targets above apply to CLI install tracking.
Your project must already expose components.json, src/payload.config.ts, the host shape checked by payload-components add. The CLI verifies this against the support matrix before touching anything.