Post lists and layouts

PostList presents links and optional images from any source. Your site owns the collection, filtering, sorting, URLs, and editorial selection. The component owns the reading layout.

This API is available in the source checkout, generated starter, and npm canary channel. Install @alkemdotdev/alkemist-components@canary for the current API; the original 1.0.0-beta.1 predates it.

Choose a layout

Without an explicit selection, the first supplied item is the lead. Set featuredHref to an item’s URL to choose another post. It appears once, followed by the remaining items in their supplied order. Coverless posts remain readable text entries without artificial image placeholders.

Use it in an existing site

---
import PostList from '@alkemdotdev/alkemist-components/post-list';
import type { PostListItem } from '@alkemdotdev/alkemist-components/post-list';
import cover from '../assets/experiment.png';

const posts: PostListItem[] = [
  {
    href: '/blog/experiment/',
    title: 'The first experiment',
    description: 'What the measurements helped us notice.',
    date: '2026-09-12',
    cover: { src: cover, alt: 'Measured response over time.', fit: 'contain' },
  },
  {
    href: '/blog/next-question/',
    title: 'The next question',
    description: 'A short entry without an image.',
  },
];
---

<PostList items={posts} layout="featured-grid" selectable />

Omit selectable for a fixed layout. When enabled, readers can change the presentation without changing the content or navigating away. Each list has independent controls. The initial layout still renders without JavaScript; the selector appears only when it can operate.

Local imported images use Astro’s image pipeline. String image URLs use an ordinary image element; the host owns their delivery. Include any deployment subpath in item URLs. The component does not fetch content, install a router, or import the full theme.

Configure the starter

The source starter exposes blogDisplay in src/lib/site.ts:

export const blogDisplay = {
  layout: 'featured-grid',
  selectable: true,
};

The Alkemist demo keeps the same setting in apps/site/src/lib/sections.ts, including its editorial featuredHref. Image selection and crop controls remain in each post’s cover metadata.

Try the layouts

Change the layout, featured item, and collection in this example. Turn selectable off to make the list fixed. Each playground keeps its own state.

---
import PostList from "@alkemdotdev/alkemist-components/post-list";
---

<PostList
  items={[{"href":"/blog/","title":"Making ideas visible","description":"An experiment in publishing research.","date":"2026-09-13","cover":{"src":"/test/torus-knot.svg","alt":"A torus knot","fit":"contain"}},{"href":"/labs/","title":"An interactive notebook","description":"Small experiments you can inspect.","date":"2026-09-12"},{"href":"/docs/","title":"Document the useful parts","description":"A reference that grows with the work.","date":"2026-09-11","cover":{"src":"/test/torus-knot.svg","alt":"Knot diagram"}}]}
  layout={"featured-grid"}
  selectable={true}
  featuredHref={""}
  label={"Recent work"}
/>