React changelog component with unread dots

Use Changelog for a release list that shows each visitor what is new since their last visit.

A "What's new" list that knows what each visitor hasn't read. Releases hang off a rail on the left: a measuring tape with versions as the major ticks (the default), or a plain line with a node per version. Releases new since the last visit carry a "New to you" chip under their version and an unread dot, and a "Before your last visit" divider heads the older ones, like the "new messages" line in a chat. A release that stays on screen for a moment is marked read and its dot fades; "Mark all as read" clears the rest in a sweep down the list while the count rolls to zero. Tag chips filter the list. Read state is stored per visitor in localStorage, and every UI string can be replaced through labels.

Quick answers

Dependencies: react, react-dom and motion 12 or newer. Nothing else.
React version: 19 or newer.
SSR and 'use client': Renders on the server. The file starts with 'use client', so the Next.js App Router can import it straight into a Server Component. In the Pages Router, Vite, React Router and Astro that line does nothing. See Troubleshooting.
Licence: MIT. Use it in any project, commercial or not.
Paid access: None. No account and no key.

Installation

shadcn

npx shadcn@latest add https://brioui.com/r/changelog.json

Manual

Copy changelog.tsx into your project, for example components/brio/changelog.tsx.
Install the peer dependency: npm install motion.
Requires React 19. The theme tokens (--ui-*) are optional; the component falls back to its own defaults.
The file starts with 'use client', so it can be imported straight from Next.js App Router server components.

Usage

TSX

import { Changelog, type Release } from '@/components/brio/changelog'

const releases: Release[] = [
  {
    version: '2.4.0',
    date: '2026-09-22',
    title: 'Saved views for reports',
    tags: ['New'],
    body: <p>Save any combination of filters and columns as a view, then share it with your team.</p>,
  },
  {
    version: '2.3.2',
    date: '2026-09-15',
    title: 'Faster search on large workspaces',
    tags: ['Improved', 'Fixed'],
    body: <p>Search results load up to three times faster in workspaces with many projects.</p>,
  },
]

export function WhatsNew() {
  return <Changelog releases={releases} />
}

On a first visit only the newest release is unread. After that, anything the visitor hasn't read is unread, and the divider reads "Since your last visit · ".

Examples

Choose what a first visit sees as new

initialSeen takes a release's version or its id. On a first visit, releases above it start unread; it and everything below count as seen. "2.3.0", "v2.3.0" and the id "v2-3-0" all point at the same release (ids default to "v" + the version with dots turned into dashes).

TSX

import { Changelog, type Release } from '@/components/brio/changelog'

export function ProductUpdates({ releases }: { releases: Release[] }) {
  return <Changelog releases={releases} storageKey="acme:changelog" initialSeen="2.3.0" />
}

Releases loaded async, with server rendering

Read state waits until releases is non-empty, so an empty first render doesn't mark everything seen. Pass locale when rendering on the server so dates match on hydration. While releases is empty the component shows its empty state (labels.empty), so show your own loading placeholder until the first fetch resolves.

TSX

import { useEffect, useState } from 'react'
import { Changelog, type Release } from '@/components/brio/changelog'

type ApiRelease = { version: string; date: string; title: string; tags: string[]; notes: string[] }

export function RemoteChangelog() {
  const [releases, setReleases] = useState<Release[]>([])
  const [loaded, setLoaded] = useState(false)

  useEffect(() => {
    fetch('/api/releases')
      .then(r => r.json() as Promise<ApiRelease[]>)
      .then(list =>
        setReleases(
          list.map(r => ({
            version: r.version,
            date: r.date,
            title: r.title,
            tags: r.tags,
            body: (
              <ul>
                {r.notes.map(n => (
                  <li key={n}>{n}</li>
                ))}
              </ul>
            ),
          })),
        ),
      )
      .finally(() => setLoaded(true))
  }, [])

  if (!loaded) return <p>Loading updates…</p>
  return <Changelog releases={releases} locale="en-US" />
}

Line rail, no filters, faster reading

rail="line" draws a plain 1px rail with a node per release instead of the default measuring tape. filters={false} hides the tag chips. dwell sets how long a release must stay on screen to count as read.

TSX

import { Changelog, type Release } from '@/components/brio/changelog'

export function CompactChangelog({ releases }: { releases: Release[] }) {
  return <Changelog releases={releases} rail="line" filters={false} dwell={1200} />
}

Stable ids for anchors and storage

Set id when versions may be renamed. The id is the anchor (#id) and the key saved as read. When two changelogs on one page could share ids, give each an anchorPrefix so their anchors stay unique (heading ids used for aria-labelledby are already scoped per instance).

TSX

import { Changelog, type Release } from '@/components/brio/changelog'

const releases: Release[] = [
  { id: 'api-2026-09', version: '2026.09', date: '2026-09-01T09:00:00Z', title: 'Webhooks v2', tags: ['New'] },
  { id: 'api-2026-08', version: '2026.08', date: '2026-08-04T09:00:00Z', title: 'Rate limit headers', tags: ['Improved'] },
]

export function ApiChangelog() {
  // anchors become #api-api-2026-09, #api-api-2026-08
  return <Changelog releases={releases} storageKey="acme:api-changelog" anchorPrefix="api-" />
}

Labels

Every fixed string can be replaced; pass only the ones you need.

TSX

import { Changelog, type Release } from '@/components/brio/changelog'

// Stand-in release data.
const releases: Release[] = [
  { version: '2.4.0', date: '2026-10-01', title: 'Faster sync', tags: ['New'], body: 'Sync is faster.' },
  { version: '2.3.0', date: '2026-09-12', title: 'Dark mode fixes', tags: ['Fixed'], body: 'Contrast fixed.' },
]

export function Example() {
  return (
    <Changelog
      releases={releases}
      labels={{
        region: 'Nouveautés',
        newSince: 'nouveautés depuis votre dernière visite',
        caughtUp: 'Vous êtes à jour',
        markAll: 'Tout marquer comme lu',
        filters: 'Filtrer les versions',
        all: 'Tout',
        unread: 'Non lu :',
        sinceLastVisit: 'Avant votre dernière visite',
        newToYou: 'Nouveau pour vous',
      }}
      locale="fr-FR"
    />
  )
}

Props

Changelog

Prop	Type	Default	Description
`releases`	`Release[]`	required	Newest first. Releases can be added at any time; new ones show up unread.
`storageKey`	`string`	`'changelog'`	localStorage key. The value is `{ seen: string[], at: number, visit: number }`: the ids read, when that list was last saved, and when the latest visit started. `sessionStorage` key `${storageKey}:last-visit` pins the previous visit's date for the rest of the browser session, so reloads don't move the divider. localStorage key for the visitor's read state.
`initialSeen`	`string`	only the newest is unread	Release version (`'2.3.0'` or `'v2.3.0'`) or id (`'v2-3-0'`). On a first visit, releases newer than it start unread; it and older ones are seen. A value matching no release makes every release unread. Accepts the release id / slug ("v2-3-0") or its version ("2.3.0", "v2.3.0"). Default: only the newest is unread.
`anchorPrefix`	`string`	`''`	Prepended to each release's anchor id and link (`#${anchorPrefix}${id}`). Leave empty for plain deep links (`#v2-3-0`); set it when two changelogs on one page share release ids.
`labels`	`Partial<ChangelogLabels>`	`English`	UI strings. See ChangelogLabels. English defaults; see `ChangelogLabels`.
`dwell`	`number`	`2500`	ms a release must stay on screen (60% visible) to count as read. ms a release must stay at least 60% visible to be marked read.
`locale`	`string`	visitor's locale	BCP 47 locale for dates. Defaults to the visitor's locale; pass it when rendering on the server.
`filters`	`boolean`	`true`	Show tag filter chips with counts. Hidden when no release has tags.
`maxFilters`	`number`	`8`	Tag chips shown before the rest fold behind an "N more" chip (`labels.moreFilters`), which expands them all and becomes "Fewer". The "All" chip and the active tag are always shown. Order: New, Improved, Fixed, then by number of releases, then alphabetically. New, Improved and Fixed come first, then by release count.
`rail`	`'line' \| 'tape'`	`'tape'`	`'tape'`: a measuring-tape rail with versions as major ticks. `'line'`: a 1px rail with a node per release.
`className`	`string`	—	Extra class on the root `<section class="cl-root">`.
`style`	`CSSProperties`	—	Inline styles on the root. Use it to set the `--changelog-*` variables.

Changelog is also the default export.

With an empty releases array the component shows labels.empty. Note that read state is only loaded once there are releases, so async data can start as [] (the empty state shows until it arrives).

Read state is stored as the set of ids seen, so removing or renaming old releases never makes other releases look unread. Marking releases read updates at but never visit, so "Since your last visit" always dates from the start of the previous visit, not from the last thing read. Read state saved before ids dropped a leading "v" from versions (vv2-3-0) is still recognised. If storage is blocked, read state lasts for the page view only.

Release

Field	Type	Default	Description
`version`	`string`	required	Shown as `v` + version. A version that already starts with `v` or `V` (`'v2.4.0'`) is shown as given. Version string, shown as "v" + version ("v" is only added when it doesn't already start with v / V).
`date`	`string`	required	ISO date. A plain `YYYY-MM-DD` is a calendar day, formatted in UTC so it never shows as the day before. A full timestamp is shown in the visitor's time zone. A date that doesn't exist (`'2026-02-29'`) or can't be parsed is left out, with a one-time console warning in development. Years before 100 (`'0001-01-01'`) are kept as written. A plain "YYYY-MM-DD" is treated as a calendar day (no time zone shift). Invalid dates are left out (dev warning).
`title`	`string`	required	Release heading.
`tags`	`string[]`	—	Tag chips and filters. `New`, `Improved` and `Fixed` (any case) get their own colour and icon; other tags get a neutral chip. Filters are case-insensitive: `New` and `new` are one chip (labelled with the first spelling in the list) and one count. Case-insensitive duplicates on one release (`['fixed', 'FIXED']`) show once; empty tags are ignored. A long tag is truncated with the full text as a tooltip.
`body`	`ReactNode`	—	Release notes, rendered as given (paragraphs, lists…).
`id`	`string`	`"v"` + version (minus a leading `v`), non-alphanumerics → `-`	Anchor + storage id. Defaults to "v" + version (minus any leading v / V) with every run of non-alphanumerics turned into "-" ("2.3.0" and "v2.3.0" → "v2-3-0"). `2.3.0` and `v2.3.0` both become `v2-3-0`. Must be unique within one changelog.

ChangelogLabels

Key	Default	Where
`region`	`'Changelog'`	Accessible name of the root `<section>`.
`newSince`	`'new since your last visit'`	After the unread count in the status line.
`caughtUp`	`'You’re all caught up'`	Status line with nothing unread.
`markAll`	`'Mark all as read'`	Button label and tooltip.
`filters`	`'Filter releases'`	Accessible name of the filter chip group.
`all`	`'All'`	First filter chip.
`unread`	`'Unread:'`	Visually hidden text before an unread release's title.
`sinceLastVisit`	`'Before your last visit'`	Heading of the divider above the releases from before the last visit, followed by `· <date>` once there was a previous visit.
`newToYou`	`'New to you'`	Chip under the version of each release that came out since the last visit.
`moreFilters`	n => `${n} more`	Chip that reveals the tag filters folded by `maxFilters`. A function of the hidden count.
`fewerFilters`	`'Fewer'`	The same chip once expanded.
`empty`	`'No releases yet'`	Shown (with an icon, and no status line or filters) when `releases` is empty.
`tag`	`t => t`	Display text of a tag, e.g. `t => ({ New: 'Nouveau', Improved: 'Amélioré' })[t] ?? t`. Translates the chip without changing its colour, icon or filter, which follow the tag as written in `releases`.

Customisation

Variants: none. The rail prop switches between the line and tape rails.
Theme tokens: --ui-ink (text, rail), --ui-accent (unread dots, divider, "New" tag, focus rings), --ui-surface (rail node fill), --ui-ok ("all caught up" icon, "Fixed" tag), --ui-info ("Improved" tag), --ui-font-mono (versions, dates, tags). Corners: --ui-radius-sm (buttons, fields, rows and tags, scaled from it), --ui-radius-pill (chips, switches, badges and round buttons). Dots and avatars stay round.
Component CSS variables: --changelog-ink, --changelog-accent, --changelog-surface, --changelog-ok, --changelog-info, --changelog-mono override the matching token for this component only. Defaults: #17140f, #d4452b, #fbf8f1, #2f7d4f, #3f7fbf, ui-monospace, Menlo, monospace.
Class names: className goes on .cl-root, which carries data-rail. Stable classes: .cl-head, .cl-status, .cl-markall, .cl-filters, .cl-chip (with aria-pressed), .cl-chip-more (the "N more" / "Fewer" chip, with aria-expanded), .cl-list, .cl-rel (one release, with data-unread), .cl-mark (version and date column), .cl-version, .cl-fresh (the "New to you" chip), .cl-entry, .cl-title, .cl-dot, .cl-tags, .cl-tag (with data-tone="new" | "improved" | "fixed" | "other"), .cl-body, .cl-divider, .cl-empty (the empty state; the root then carries data-empty).
Labels: labels replaces every UI string (see ChangelogLabels). Tag text comes from your data.

Responsive behaviour

Under 400px of width the version and date sit on one line above each entry, so release notes get the full width.
Expanded tag filters scroll inside a short box there.
Release titles are capped at 70 characters per line.
On touch screens the chips, mark-all button and version permalinks have 44px targets.

Keyboard

Key	Action
`Tab`	Move through "Mark all as read", the filter chips and each release's version link.
`Enter` / `Space`	Press the focused button: mark all as read, or switch filter.
`Enter` (on a version link)	Follow the `#id` anchor (`#${anchorPrefix}${id}`) to that release.

Accessibility

The root is a <section aria-label="Changelog"> (labels.region) with an ordered list. Each release is an <article> labelled by its <h3> title (heading ids are scoped per instance with useId), with a <time dateTime>.
Unread releases have visually hidden "Unread:" text before the title.
The status line ("3 new since your last visit" / "You’re all caught up") is a polite live region.
Filter chips are aria-pressed buttons in a group labelled "Filter releases".
On screens 560 px wide or less, and wherever the component itself is 440 px wide or less (a container query on .cl-root, e.g. in a sidebar or card), the rail narrows and "Mark all as read" shrinks to its icon and keeps its accessible name. A long status line wraps instead of being squeezed; a long "Mark all as read" label truncates, with the full text as a tooltip.
Long content stays inside the component: long versions truncate (full version in the tooltip), titles, links and hashes in the notes wrap, <pre> blocks scroll sideways, and titles and notes get dir="auto" so right-to-left text lays out correctly.
Reduced motion: dots, entries and the divider appear and disappear with a fade, "Mark all as read" clears at once with no sweep, and the count jumps instead of rolling.

Agent prompt

Add the Brio UI "Changelog" component to this project.
1. Run `npx shadcn@latest add https://brioui.com/r/changelog.json`.
2. Make sure `motion` is installed and React is 19 or newer.
3. Import `Changelog` from the file the CLI created and render it with `releases` (newest first: { version, date, title, tags?, body?, id? }[]) and a project-specific `storageKey`.
4. Set `initialSeen` to the version (e.g. "2.3.0") or id of the last release first-time visitors should treat as already seen; pass `locale` if the page is server-rendered.
Full docs: https://brioui.com/docs/components/changelog.md

ChangelogFree

Worst case