PostsList

PostsList renders a list of posts as a grid or a row list, with an optional full-bleed highlight card, a lead grid, paging and injected items such as ads. Latest Posts, archive listings, related posts and the Payload posts block all render through it. It takes plain PostView objects, so it works with any data source, not only Payload.

import { PostsList, type PostView } from '@systhemaui/next'

function post(id: number, title: string, label: string, image: string): PostView {
  return {
    id,
    title,
    label,
    href: '#',
    excerpt: 'How a small team keeps a large site consistent without slowing its editors down.',
    tags: [],
    postType: 'article',
    author: { name: 'Mira Kovač' },
    publishedAt: `2026-09-${10 + id}T09:00:00.000Z`,
    media: { url: `/demo-assets/${image}`, alt: '', width: 1800, height: 1200 },
    doc: null,
  }
}

const posts = [
  post(4, 'Designing with tokens from day one', 'Design', 'city.webp'),
  post(3, 'A calmer content model for editors', 'Editorial', 'workspace.webp'),
  post(2, 'Shipping a multilingual site in a week', 'Engineering', 'mountains.webp'),
  post(1, 'A field guide to spacing', 'Design', 'coast.webp'),
]

export default function Demo() {
  return <PostsList items={posts} view="grid3" highlightFirst />
}

ImportLink to this section

import { PostsList } from '@systhemaui/next'

In a React app without Next.js, import it from @systhemaui/react. The Next.js version renders media with next/image and links with next/link; see Next.js.

LayoutsLink to this section

view sets the layout of the list: grid2, grid3, grid4 (the default) or row. Every grid is one column below md. grid2 turns two-up from md; grid3 and grid4 are two-up from md and three-up or four-up from lg. Each card gets the matching layout, which sets its media aspect ratio and which parts it shows (see PostCard).

GridLink to this section

import { PostsList, type PostView } from '@systhemaui/next'

function post(id: number, title: string, label: string, image: string): PostView {
  return {
    id,
    title,
    label,
    href: '#',
    excerpt: 'How a small team keeps a large site consistent without slowing its editors down.',
    tags: [],
    postType: 'article',
    author: { name: 'Mira Kovač' },
    publishedAt: `2026-09-${10 + id}T09:00:00.000Z`,
    media: { url: `/demo-assets/${image}`, alt: '', width: 1800, height: 1200 },
    doc: null,
  }
}

const posts = [
  post(3, 'A calmer content model for editors', 'Editorial', 'workspace.webp'),
  post(2, 'Shipping a multilingual site in a week', 'Engineering', 'city.webp'),
  post(1, 'A field guide to spacing', 'Design', 'coast.webp'),
]

export default function Demo() {
  return <PostsList items={posts} view="grid3" />
}

Row list with dividersLink to this section

row puts the media beside the text from md up and stacks it below. Add dividers to draw a 1px --color-separator-line hairline between rows. Grids ignore dividers.

import { PostsList, type PostView } from '@systhemaui/next'

function post(id: number, title: string, label: string, image: string): PostView {
  return {
    id,
    title,
    label,
    href: '#',
    tags: [],
    postType: 'article',
    author: { name: 'Mira Kovač' },
    publishedAt: `2026-09-${10 + id}T09:00:00.000Z`,
    media: { url: `/demo-assets/${image}`, alt: '', width: 1800, height: 1200 },
    doc: null,
  }
}

const posts = [
  post(3, 'A calmer content model for editors', 'Editorial', 'workspace.webp'),
  post(2, 'Shipping a multilingual site in a week', 'Engineering', 'city.webp'),
  post(1, 'A field guide to spacing', 'Design', 'coast.webp'),
]

export default function Demo() {
  return <PostsList items={posts} view="row" dividers />
}

Lead grid and tail listLink to this section

leadCount renders the first N cards in a separate lead grid, laid out by leadView (default grid3), and the rest below it in view. With highlightFirst, the count starts after the highlight card. A leadCount of 0, or one at least as large as the number of cards, renders a single uniform list.

import { PostsList, type PostView } from '@systhemaui/next'

function post(id: number, title: string, label: string, image: string): PostView {
  return {
    id,
    title,
    label,
    href: '#',
    excerpt: 'How a small team keeps a large site consistent without slowing its editors down.',
    tags: [],
    postType: 'article',
    author: { name: 'Mira Kovač' },
    publishedAt: `2026-09-${10 + id}T09:00:00.000Z`,
    media: { url: `/demo-assets/${image}`, alt: '', width: 1800, height: 1200 },
    doc: null,
  }
}

const posts = [
  post(5, 'Designing with tokens from day one', 'Design', 'city.webp'),
  post(4, 'A calmer content model for editors', 'Editorial', 'workspace.webp'),
  post(3, 'Shipping a multilingual site in a week', 'Engineering', 'mountains.webp'),
  post(2, 'A field guide to spacing', 'Design', 'coast.webp'),
  post(1, 'Choosing a type pairing', 'Design', 'abstract-square.webp'),
]

export default function Demo() {
  return (
    <PostsList items={posts} highlightFirst leadCount={2} leadView="grid2" view="row" dividers />
  )
}

ExamplesLink to this section

GapsLink to this section

Grids default to a sm column gap and a md row gap, and the row list to a md row gap. gapX and gapY override one axis each with a gap token (none, xs, sm, md, lg, xl, 2xl, 3xl), applied inline as column-gap: var(--gap-<size>) and row-gap: var(--gap-<size>).

<PostsList items={posts} view="grid4" gapX="md" gapY="lg" />

Card optionsLink to this section

cardConfig is passed to every default card: show turns parts on or off, classNames overrides a part's classes, and aspectRatio, mediaWidth, bodyAlign and mediaGap set inline presentation values. highlightConfig does the same for the highlight card, and leadCardConfig for the lead grid (it falls back to cardConfig). The parts are listed on PostCard.

import { PostsList, type PostView } from '@systhemaui/next'

function post(id: number, title: string, label: string, image: string): PostView {
  return {
    id,
    title,
    label,
    href: '#',
    excerpt: 'How a small team keeps a large site consistent without slowing its editors down.',
    tags: [],
    postType: 'article',
    author: { name: 'Mira Kovač' },
    publishedAt: `2026-09-${10 + id}T09:00:00.000Z`,
    media: { url: `/demo-assets/${image}`, alt: '', width: 1800, height: 1200 },
    doc: null,
  }
}

const posts = [
  post(3, 'A calmer content model for editors', 'Editorial', 'workspace.webp'),
  post(2, 'Shipping a multilingual site in a week', 'Engineering', 'city.webp'),
  post(1, 'A field guide to spacing', 'Design', 'coast.webp'),
]

export default function Demo() {
  return (
    <PostsList
      items={posts}
      view="grid3"
      cardConfig={{ show: { excerpt: false, readMore: true }, aspectRatio: '1/1' }}
    />
  )
}

Loading more postsLink to this section

items is the first page. To load more, set loading and pass fetchMore(page), which returns the next page's PostView[], together with paging ({ total, page, limit }) so the list knows when it has everything:

PostsList never fetches on its own, so fetchMore is where you call your API. A function prop makes the calling module a client module.

'use client'

import { PostsList, type PostView } from '@systhemaui/next'

function post(id: number, title: string, image: string): PostView {
  return {
    id,
    title,
    label: 'Journal',
    href: '#',
    tags: [],
    postType: 'article',
    author: { name: 'Mira Kovač' },
    publishedAt: `2026-09-${10 + id}T09:00:00.000Z`,
    media: { url: `/demo-assets/${image}`, alt: '', width: 1800, height: 1200 },
    doc: null,
  }
}

const all = [
  post(6, 'Designing with tokens from day one', 'mountains.webp'),
  post(5, 'A calmer content model for editors', 'workspace.webp'),
  post(4, 'Shipping a multilingual site in a week', 'city.webp'),
  post(3, 'A field guide to spacing', 'coast.webp'),
  post(2, 'Choosing a type pairing', 'abstract-square.webp'),
  post(1, 'Photographing for the web', 'forest-portrait.webp'),
]

async function fetchPage(page: number) {
  await new Promise((resolve) => setTimeout(resolve, 600))
  return all.slice((page - 1) * 3, page * 3)
}

export default function Demo() {
  return (
    <PostsList
      items={all.slice(0, 3)}
      view="grid3"
      loading="loadMore"
      fetchMore={fetchPage}
      paging={{ total: all.length, page: 1, limit: 3 }}
    />
  )
}

loadMoreButton styles the button: variant (a button variant, the default variant when unset), title, iconBeforeHtml / iconAfterHtml (icon markup strings) and align (left, center or right). In pagination mode the highlight and the lead grid appear on page 1 only; prefer loadMore or infinite for a lead/tail listing, because they append to the tail.

With a highlight or a lead grid, page 1 holds limit cards plus those extra ones and later pages hold limit. The listing helpers compute the offsets your fetchMore needs.

Injecting itemsLink to this section

injectItems is called after every card with { index, total, section, isLeadEnd }; return a node to render it after that card, or null. In a split listing it is called once more with isLeadEnd: true between the lead grid and the tail, and that node renders full width in a .posts-list-interspace wrapper, outside both containers.

<PostsList
  items={posts}
  leadCount={6}
  view="row"
  injectItems={({ index, isLeadEnd }) =>
    isLeadEnd ? <AdBanner /> : index > 0 && index % 8 === 0 ? <AdTile /> : null
  }
/>

Custom cardsLink to this section

CardIsland and HighlightIsland replace the default cards with your own component, which receives { post }. They must be client components ('use client'), and they handle their own linking. See Customizing the presentation.

ThemeLink to this section

theme sets data-theme on the list, so the cards resolve against that color-system mode. See Themes and backgrounds.

PropsLink to this section

Two props are not obvious from their types:

• LinkComponent wraps each default card and the highlight in a link to post.href, with display: contents so the link does not take part in the grid. It defaults to <a> in React and to next/link in Next.js. Islands are never wrapped.
• labels translates the built-in text: loadMore, loading, previous, next, readMore, pagination (the pagination landmark's name) and empty (default "No posts found.").

RevealLink to this section

Each card reveals on its own as it scrolls in. The list root and the divider container are <Stack allowChildAnimation>, because a plain Stack cancels the reveals inside it. In a grid row the cards cascade left to right: the posts CSS layer gives each column one delay step of var(--tw-stagger-delay, 120ms), only at the breakpoints where that column count applies. One-column grids and the row view are not staggered. Set --tw-stagger-delay to retune the step, or pass disableAnimation to turn the reveals off. See Motion.

HTML and CSSLink to this section

The layout comes from the posts CSS layer (blocks.posts, on by default), not from Tailwind grid utilities, so it renders in any project whatever Tailwind scans. The layer styles .posts-list*, .post-card*, .post-highlight*, .post-meta*, .archive-filter* and .post-share*. Turn it off with blocks: { posts: false } only when the project does not use posts. See Component CSS blocks.

<div class="stack flex flex-col gap-md aos-allow-children posts-list posts-list-grid3">
  <div class="posts-list-grid posts-list-grid-3">
    <a class="post-card-link contents" href="/journal/designing-with-tokens">
      <article class="post-card post-card-grid3 flex flex-col gap-4">
        <div class="post-card-media media-wrapper aspect-[4/3]">
          <img src="/media/mountains.webp" alt="" loading="lazy" />
        </div>
        <div class="post-card-body flex flex-col gap-4">
          <span class="post-card-label text-label">Design</span>
          <h3 class="post-card-title color-heading text-h4">Designing with tokens from day one</h3>
          <div class="post-meta post-card-meta text-small flex flex-wrap items-center gap-x-2">
            <span class="post-meta-author">Mira Kovač</span>
            <span class="post-meta-separator" aria-hidden="true">•</span>
            <time class="post-meta-date" datetime="2026-09-14">September 14, 2026</time>
          </div>
          <p class="post-card-excerpt color-body text-body line-clamp-3">How a small team…</p>
        </div>
      </article>
    </a>
  </div>
</div>

The list is at most --container-width wide and centered, so it does not bleed edge to edge outside a Section. The card root sets its color from --color-typography-body, so the title, excerpt and byline follow the active color system on a themed band.

The per-column stagger lives in this layer and out-declares the reveal animation's own animation shorthand. To override the delay from your own CSS, use the app layer (or !important), not a more specific selector. See Cascade layers.

Next.jsLink to this section

The @systhemaui/next PostsList has the same props as the React one and fills in two defaults:

• Cards render media with next/image (fill, objectFit="cover") and a sizes hint from sizesForLayout(view).
• The highlight card renders fill, sizes="100vw" and priority, so it loads eagerly as the likely LCP image.
• Each card links through next/link.

A renderImage, renderHighlightImage or LinkComponent you pass wins over these defaults. The component is a client component; use it from server components with serializable props, and from a client module when you pass fetchMore, injectItems or islands.

In a Payload project, @systhemaui/payload/next also exports the archive pipeline (resolveArchiveData, PostsListClient, ArchiveFilterProvider, useArchiveFilters, ArchiveFilterControl) for building a custom archive with search, load more and ads. See Archive pages.

AccessibilityLink to this section

• The list sets aria-busy while a page loads.
• In loadMore and infinite modes a visually hidden role="status" region announces the loading text, then the shown / total count after each page.
• The empty state ("No posts found.") is an aria-live="polite" region.
• Pagination is a <nav> named by labels.pagination; its buttons have visually hidden "Previous" and "Next" text, and changing page scrolls the top of the listing into view.
• The whole card is one link, so its text (label, title, byline and excerpt) is the link's name. Keep titles short and descriptive.
• Card titles are <h3> and the highlight title is <h2>. When the page outline needs other levels, render the standalone cards with headingLevel, or use an island.

RelatedLink to this section

• PostCard and HighlightCard
• Posts view model and helpers
• ArchiveSearchFilter
• Posts block
• Listings and sharing