Thumbnail List

When to use

A linked thumbnail-list block — small image + title + meta line per row, each row a single link target. Built for sidebars and dropdowns: related posts, popular articles, search-suggestion results, "up next" media queues, file-picker recents.

Use it for short lists (3–10 items typically; cap at ~20). For longer result sets reach for data-table or magazine-layout.

Basic example

import { ThumbnailList } from "@/components/thumbnail-list"

const items = [
  { id: "1", title: "Sustainable cities", imageSrc: "/img/1.jpg", meta: "5 min read", href: "/news/1" },
  { id: "2", title: "Public transit on the rebound", imageSrc: "/img/2.jpg", meta: "3 min read", href: "/news/2" },
]

export function Example() {
  return <ThumbnailList items={items} labels={{ heading: "Related" }} />
}

No frame (inline)

Pass framed={false} to drop the card chrome. Useful in a search-suggestions dropdown, a modal, or any other surface that already provides its own framing.

<ThumbnailList items={searchHits} framed={false} />

Custom meta rendering

The default meta render shows item.meta as a plain string. Pass renderMeta(item) to render dates, badges, scores, or anything else.

<ThumbnailList
  items={posts}
  renderMeta={(item) => (
    <time className="text-xs text-muted-foreground mt-1 block" dateTime={item.publishedAt}>
      {formatRelative(item.publishedAt)}
    </time>
  )}
/>

Polymorphic link

Per-item href drives navigation. By default the row link renders as a native <a>. Pass linkComponent for router-aware links (e.g. next/link or RemixLink).

import Link from "next/link"

<ThumbnailList items={items} linkComponent={Link} />

Empty state

When items is empty, the default empty fallback renders with labels.emptyText. For a richer custom UI, pass emptyState as a ReactNode — it replaces the default message.

<ThumbnailList
  items={[]}
  labels={{
    heading: "Recently viewed",
    emptyText: "Nothing here yet — articles you read will show up.",
  }}
/>

Notes

• Items render as <li> inside a <ul>. The link wraps the row content; keyboard focus and hover both shift the title color (group-hover:text-primary / group-focus-visible:text-primary).
• The header icon is decorative (aria-hidden). Pass headerIcon={null} to hide it entirely.
• Items without href render as plain rows (no link affordance). Useful when you want the visual but not the navigation.
• Thumbnails default to w-20 h-16 (5:4 landscape). Override via imageClassName for square / portrait / other shapes.
• The component is exported as React.memo. Pass stable refs for linkComponent / headerIcon / renderMeta for memoization to hold.
• Don't reach for this for paginated or virtualized lists — it renders all items eagerly. Cap input at ~20.