# Post grid (themes.dev UI block)

The latest blog posts as story cards, picture on top, under a section header with a link to every post; page links on an index. No card ends a row alone. Black and white, dark mode, shadcn-compatible; React, Astro and plain HTML.

34% of 139 news overviews and 16% of 671 home pages we studied have a posts or changelog section.

## Install

- React: `npx shadcn@latest add https://www.themes.dev/ui/r/post-grid.json`
- Astro: `npx shadcn@latest add https://www.themes.dev/ui/r/astro/post-grid.json`
- HTML: https://www.themes.dev/ui/r/html/post-grid.html (with https://www.themes.dev/ui/r/html/caseroom.css)

Page: https://www.themes.dev/ui/blocks/post-grid/ · Rules for agents: https://www.themes.dev/ui/AGENT.md

## Code

### post-grid.astro

```astro
---
import Link from '@/components/ui/link.astro';
import Pagination from '@/components/ui/pagination.astro';
import SectionHeader from '@/components/ui/section-header.astro';
import StoryCard from '@/components/ui/story-card.astro';
import { cn } from '@/lib/utils';
import { postGrid as c, type PostGridContent } from './post-grid.classes';

type Props = PostGridContent & { class?: string };
const { kicker, title, description, link, posts, pagination, id, class: className } = Astro.props;
---

<section aria-labelledby={`${id}-title`} class={cn(c.root, className)}>
  <div class={c.inner}>
    <SectionHeader id={`${id}-title`} kicker={kicker} title={title} description={description}>
      {link && <Link href={link.href} variant="standalone">{link.label}</Link>}
    </SectionHeader>
    <ul role="list" class={c.list(posts.length)}>
      {
        posts.map((p) => (
          <li class={c.item}>
            <StoryCard {...p} class={c.card} />
          </li>
        ))
      }
    </ul>
    {pagination && <Pagination current={pagination.page} total={pagination.pages} href={pagination.href} label="Blog pages" class={c.pagination} />}
  </div>
</section>
```

### post-grid.classes.ts

```tsx
/** Post grid: a section header (with an optional link to every post), then the latest posts as story cards with the
 *  picture on top, and optional page links under them. Columns follow the block's own width and leave no card alone on
 *  a row: three or six posts go three across from 56rem (six go two across from 36rem first), two or four go two across
 *  from 36rem, other counts stack. */
export const postGrid = {
  root: '@container bg-background px-6 py-16 text-foreground @3xl:py-24',
  inner: 'mx-auto flex max-w-6xl flex-col gap-12',
  list: (count: number) =>
    [
      'm-0 grid list-none gap-6 p-0',
      // Six (or twelve) split evenly into twos and threes; three or nine only into threes, so they stack until then.
      count % 6 === 0 ? '@xl:grid-cols-2 @4xl:grid-cols-3' : count % 3 === 0 ? '@4xl:grid-cols-3' : count % 2 === 0 ? '@xl:grid-cols-2' : '',
    ].join(' '),
  item: 'flex',
  // The picture row keeps its ratio; a taller neighbour's extra height goes to the text, so the kickers line up.
  card: 'w-full grid-rows-[auto_1fr]',
  // The first control's padding steps outside the content edge, so its chevron lines up with the cards' edge.
  pagination: '-ms-2.5 self-start',
};

/** One post, as the story card takes it: kicker is the topic in words, meta the date and reading time. */
export type Post = { title: string; href: string; kicker?: string; description?: string; meta?: string; image?: { src: string; alt: string } };
export type PostGridContent = {
  kicker?: string;
  title: string;
  description?: string;
  /** Beside the heading: the blog index (All posts, /blog). */
  link?: { href: string; label: string };
  /** One to nine, newest first. */
  posts: Post[];
  /** Page links under the posts, on a blog index. href(n) is page n's address. */
  pagination?: { page: number; pages: number; href: (page: number) => string };
  /** Unique on the page; ids the heading. */
  id: string;
};
```

### post-grid.tsx

```tsx
import { Link } from '@/components/ui/link';
import { Pagination } from '@/components/ui/pagination';
import { SectionHeader } from '@/components/ui/section-header';
import { StoryCard } from '@/components/ui/story-card';
import { cn } from '@/lib/utils';
import { postGrid as c, type PostGridContent } from './post-grid.classes';

export type PostGridProps = PostGridContent & { className?: string };

/** A section header and the latest posts as story cards, picture on top; optional page links under them. */
export function PostGrid({ kicker, title, description, link, posts, pagination, id, className }: PostGridProps) {
  return (
    <section aria-labelledby={`${id}-title`} className={cn(c.root, className)}>
      <div className={c.inner}>
        <SectionHeader id={`${id}-title`} kicker={kicker} title={title} description={description}>
          {link && <Link href={link.href} variant="standalone">{link.label}</Link>}
        </SectionHeader>
        <ul role="list" className={c.list(posts.length)}>
          {posts.map((p) => (
            <li key={p.href + p.title} className={c.item}>
              <StoryCard {...p} className={c.card} />
            </li>
          ))}
        </ul>
        {pagination && <Pagination current={pagination.page} total={pagination.pages} href={pagination.href} label="Blog pages" className={c.pagination} />}
      </div>
    </section>
  );
}
```
