# Changelog list (themes.dev UI block)

Releases newest first: the date and version beside the title, black and white tags and a line; a link to the full changelog and page links. 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/changelog-list.json`
- Astro: `npx shadcn@latest add https://www.themes.dev/ui/r/astro/changelog-list.json`
- HTML: https://www.themes.dev/ui/r/html/changelog-list.html (with https://www.themes.dev/ui/r/html/caseroom.css)

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

## Code

### changelog-list.astro

```astro
---
import Badge from '@/components/ui/badge.astro';
import Link from '@/components/ui/link.astro';
import Pagination from '@/components/ui/pagination.astro';
import SectionHeader from '@/components/ui/section-header.astro';
import { cn } from '@/lib/utils';
import { changelogList as c, formatDate, TAG_BADGE, TAG_LABEL, type ChangelogListContent } from './changelog-list.classes';

type Props = ChangelogListContent & { class?: string };
const { kicker, title, description, link, releases, 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>
    <ol role="list" class={c.list}>
      {
        releases.map((r) => (
          <li>
            <article class={c.entry}>
              <div class={c.body}>
                <h3 class={c.title}><a href={r.href} class={c.link}>{r.title}</a></h3>
                {r.tags?.length ? (
                  <ul role="list" aria-label="Changes" class={c.tags}>
                    {r.tags.map((t) => (
                      <li><Badge variant={TAG_BADGE[t]}>{TAG_LABEL[t]}</Badge></li>
                    ))}
                  </ul>
                ) : null}
                {r.summary && <p class={c.summary}>{r.summary}</p>}
              </div>
              <p class={c.meta}>
                <time datetime={r.date}>{formatDate(r.date)}</time>
                {r.version && <span class={c.version}><span class="sr-only">Version </span>{r.version}</span>}
              </p>
            </article>
          </li>
        ))
      }
    </ol>
    {pagination && <Pagination current={pagination.page} total={pagination.pages} href={pagination.href} label="Changelog pages" class={c.pagination} />}
  </div>
</section>
```

### changelog-list.classes.ts

```tsx
/** Changelog list: a section header (with an optional link to the full changelog), then releases newest first. Each
 *  release is one row: the date and version on the start side, the title (the release's one link, stretched over the
 *  row), its tags and a line or two. Releases separate by space; the date column carries the order. Tags are words in
 *  black and white badges: a status, not an action, so no colour (Deprecated reads as a word, not as red). */
export const changelogList = {
  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: 'm-0 flex list-none flex-col gap-12 p-0 @3xl:gap-14',
  // The article positions the title link's ::after, which covers the whole release.
  entry: 'group relative isolate grid gap-3 @3xl:grid-cols-4 @3xl:items-start @3xl:gap-x-10',
  // Read after the title (DOM order), shown before it. Top-aligned with a nudge, not baseline: the title link is
  // inline-block (24px target), so a two-line title would pull a baseline-aligned date down.
  meta: 'order-first flex flex-wrap items-baseline gap-x-3 gap-y-1 text-sm text-muted-foreground tabular-nums @3xl:flex-col @3xl:gap-y-1 @3xl:pt-1',
  version: 'font-medium text-foreground',
  body: 'flex min-w-0 flex-col gap-3 @3xl:col-span-3',
  title: 'text-xl leading-snug font-semibold tracking-[-0.02em] text-balance',
  link: 'inline-block min-h-6 rounded-sm underline decoration-transparent underline-offset-4 transition-[text-decoration-color] after:absolute after:inset-0 after:z-10 group-hover:decoration-foreground/40 hover:decoration-foreground active:decoration-2',
  tags: 'm-0 flex list-none flex-wrap gap-2 p-0',
  summary: 'max-w-prose text-base text-pretty text-muted-foreground',
  pagination: '-ms-2.5 self-start',
};

export const RELEASE_TAGS = ['new', 'improved', 'fixed', 'deprecated'] as const;
export type ReleaseTag = (typeof RELEASE_TAGS)[number];
export const TAG_LABEL: Record<ReleaseTag, string> = { new: 'New', improved: 'Improved', fixed: 'Fixed', deprecated: 'Deprecated' };
/** New stands out (filled); the others stay quiet. */
export const TAG_BADGE: Record<ReleaseTag, 'default' | 'secondary' | 'outline'> = { new: 'default', improved: 'secondary', fixed: 'outline', deprecated: 'outline' };

const MONTHS = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
/** 2026-10-28 → 28 October 2026. By hand rather than Intl, so the server and the browser write the same text. */
export const formatDate = (iso: string) => {
  const [y, m, d] = iso.split('-').map(Number);
  return `${d} ${MONTHS[m - 1]} ${y}`;
};

export type Release = {
  title: string;
  href: string;
  /** Released, YYYY-MM-DD. */
  date: string;
  /** 2.8.0, or leave it out for a product without versions. */
  version?: string;
  /** Up to three of new, improved, fixed, deprecated. */
  tags?: ReleaseTag[];
  /** One or two sentences. */
  summary?: string;
};
export type ChangelogListContent = {
  kicker?: string;
  title: string;
  description?: string;
  /** Beside the heading: the full changelog. */
  link?: { href: string; label: string };
  /** Newest first. */
  releases: Release[];
  pagination?: { page: number; pages: number; href: (page: number) => string };
  /** Unique on the page; ids the heading. */
  id: string;
};
```

### changelog-list.tsx

```tsx
import { Badge } from '@/components/ui/badge';
import { Link } from '@/components/ui/link';
import { Pagination } from '@/components/ui/pagination';
import { SectionHeader } from '@/components/ui/section-header';
import { cn } from '@/lib/utils';
import { changelogList as c, formatDate, TAG_BADGE, TAG_LABEL, type ChangelogListContent } from './changelog-list.classes';

export type ChangelogListProps = ChangelogListContent & { className?: string };

/** Releases newest first: the date and version beside the title, its tags and a line; optional page links. */
export function ChangelogList({ kicker, title, description, link, releases, pagination, id, className }: ChangelogListProps) {
  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>
        <ol role="list" className={c.list}>
          {releases.map((r) => (
            <li key={r.href}>
              <article className={c.entry}>
                <div className={c.body}>
                  <h3 className={c.title}><a href={r.href} className={c.link}>{r.title}</a></h3>
                  {r.tags?.length ? (
                    <ul role="list" aria-label="Changes" className={c.tags}>
                      {r.tags.map((t) => (
                        <li key={t}><Badge variant={TAG_BADGE[t]}>{TAG_LABEL[t]}</Badge></li>
                      ))}
                    </ul>
                  ) : null}
                  {r.summary && <p className={c.summary}>{r.summary}</p>}
                </div>
                <p className={c.meta}>
                  <time dateTime={r.date}>{formatDate(r.date)}</time>
                  {r.version && <span className={c.version}><span className="sr-only">Version </span>{r.version}</span>}
                </p>
              </article>
            </li>
          ))}
        </ol>
        {pagination && <Pagination current={pagination.page} total={pagination.pages} href={pagination.href} label="Changelog pages" className={c.pagination} />}
      </div>
    </section>
  );
}
```
