Skip to content
themes.dev
    Style: Wireframe

    Blocks · Marketing

    Post grid

    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.

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

    Blog

    From the workshop

    Notes on the components: what we built, and why it works the way it does.

    Both previews render the same markup; the HTML tab below is that markup without a framework.

    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

    Or copy the files below into your project. They need clsx, tailwind-merge and the components they import, and the themes.dev UI theme. The HTML needs only the compiled CSS.

    post-grid.classes.ts
    /** 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
    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>
      );
    }