Related Posts

Installation

npx payload-components add related-posts

What it installs

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.

Each entry in posts carries:

Usage

Import the component into your article template and pass public display content as props. The install adds no admin fields. Your template controls content loading and publishing.

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.

Requirements