Post componentsRelated

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-posts
Manualnpx shadcn@latest add https://www.payload-components.xyz/r/related-posts.json

This 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
  1. 01
    Write the brief before the blockEditors know what a page needs to say. Start there, then decide which fields the block deserves.
  2. 02
    Drafts are a feature, not a statePreview, review, and schedule changes without a second CMS or a staging copy of the site.
  3. 03
    Fewer fields, better pagesEvery optional field is a decision you hand to an editor. Make fewer of them, and make them count.
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.

Component.tsx

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.