CHANGELOG

Changelog Timeline.

Release notes on a vertical timeline. Filter by tag, expand an entry for details, and the rail fills down to the entry you're reading.

  1. v3.4.0

    Command palette in the dashboard

    • Feature

    Press ⌘K anywhere to jump to a project, an invoice, or a setting.

    • Search matches names, customer emails, and invoice numbers.
    • Recent commands appear first when the search is empty.
    • Works with screen readers through the combobox pattern.
  2. v3.3.2

    Faster invoice exports

    • Improvement

    Large CSV exports now stream as they're generated instead of waiting for the whole file.

    An export of 50,000 invoices now starts downloading in under a second. Previously it could take two minutes.

  3. v3.3.1

    No more duplicate reminder emails

    • Fix

    Customers with two billing contacts were getting the same reminder twice.

  4. v3.3.0

    Team roles

    • Feature

    Give teammates view-only, billing, or admin access.

    • Existing members keep admin access.
    • View-only members can't see payment methods.
  5. v3.2.4

    Due dates near midnight

    • Fix

    Due dates now use the customer's time zone instead of yours.

  6. v3.2.0

    Dark mode

    • Feature
    • Improvement

    The dashboard follows your system theme, or you can pick one in Settings.

  7. v3.1.0

    Recurring invoices

    • Feature

    Send the same invoice every week, month, or quarter.

Showing all 7 updates.

REACT + TYPESCRIPT + CSSMIT LICENSE

Installation

In a project with React and shadcn configured, run:

npx shadcn@latest add https://aduneer.github.io/opalframe/r/changelog-timeline.json

Copies the component and its stylesheet into components/ui. No additional runtime dependencies. Tailwind classes work through className.

For manual installation, copy both files from Source below. Keep the CSS import alongside the component.

Usage

import { ChangelogTimeline } from "@/components/ui/changelog-timeline";

export default function Example() {
  return (
    <ChangelogTimeline
      maxHeight={480}
      entries={[
        {
          id: "3.4.0", version: "v3.4.0", date: "2026-10-08",
          title: "Command palette", tags: ["Feature"],
          summary: "Press ⌘K to jump anywhere.",
          details: <p>Search matches names and invoice numbers.</p>,
        },
        {
          id: "3.3.1", version: "v3.3.1", date: "2026-09-22",
          title: "No more duplicate emails", tags: ["Fix"],
        },
      ]}
    />
  );
}

Customize

Colors and sizes are scoped CSS variables. Override them on your own class.

<ChangelogTimeline entries={entries} className="your-changelog" />

.your-changelog {
  --changelog-accent: #a6cfff;
  --changelog-line: #3f4f64;
  --changelog-meta-width: 140px;
}

/* Each tag has a data-tag attribute you can color. */
.your-changelog [data-tag="fix"] {
  color: #ffabb9;
}

Props

PropTypeWhat it does
entriesChangelogEntry[]Unique id, ISO date, and title, plus an optional version, summary, tags, and details. Entries render in the order given.
filtersbooleanShow a filter for each tag above the timeline. Defaults to true.
filter / defaultFilterstring | nullControlled or initial tag filter. null shows every entry.
onFilterChange(tag: string | null) => voidCalled when a filter is chosen.
defaultExpandedstring[]Entry IDs whose details start open.
maxHeightnumber | stringScroll inside the timeline instead of the page. The rail follows whichever one scrolls.
localestringDate formatting locale. Defaults to en-US so server and client render the same text.
label / className / reducedMotionstring / string / booleanAccessible name (defaults to Changelog), root customization, and turning off transitions in addition to the OS preference.

Accessibility & motion

Filters are toggle buttons with a pressed state, and a status message announces how many entries are shown. Detail toggles use aria-expanded, their names include the entry title, and closed details are inert. Dates use the time element. When the timeline scrolls on its own, the scroll area is a labelled region that can be focused and scrolled with the keyboard. The rail and dots are decorative. Reduced motion removes the rail and expand transitions.

Dependencies

React only. Styles live in a plain CSS file next to the component, and Tailwind utilities work through className.

Source

changelog-timeline.tsx
"use client";

import {
  useEffect,
  useId,
  useRef,
  useState,
  type CSSProperties,
  type ReactNode,
} from "react";
import "./changelog-timeline.css";

export interface ChangelogEntry {
  id: string;
  /** ISO date, such as 2026-10-01. */
  date: string;
  title: string;
  version?: string;
  summary?: string;
  /** Categories used by the filters, such as "Feature" or "Fix". */
  tags?: string[];
  /** Expandable details. Entries without details have no toggle. */
  details?: ReactNode;
}

export interface ChangelogTimelineProps {
  entries: ChangelogEntry[];
  /** Show a filter for each tag above the timeline. */
  filters?: boolean;
  /** Controlled or initial tag filter; null shows every entry. */
  filter?: string | null;
  defaultFilter?: string | null;
  onFilterChange?: (tag: string | null) => void;
  defaultExpanded?: string[];
  /** Scroll inside the timeline instead of the page; the rail follows either. */
  maxHeight?: number | string;
  /** Fixed by default so server and client format dates identically. */
  locale?: string;
  label?: string;
  className?: string;
  reducedMotion?: boolean;
}

type Rail = { left: number; top: number; height: number; progress: number };

/** A release timeline whose rail fills to the entry currently in view. */
export function ChangelogTimeline({
  entries,
  filters = true,
  filter,
  defaultFilter = null,
  onFilterChange,
  defaultExpanded = [],
  maxHeight,
  locale = "en-US",
  label = "Changelog",
  className = "",
  reducedMotion = false,
}: ChangelogTimelineProps) {
  const uid = useId();
  const scroller = useRef<HTMLDivElement>(null);
  const list = useRef<HTMLOListElement>(null);
  const [internalFilter, setInternalFilter] = useState(defaultFilter);
  const [expanded, setExpanded] = useState(() => new Set(defaultExpanded));
  const [current, setCurrent] = useState<string>();
  const [rail, setRail] = useState<Rail>();
  const tags = [...new Set(entries.flatMap((entry) => entry.tags ?? []))];
  const active = filter !== undefined ? filter : internalFilter;
  const tag = active && tags.includes(active) ? active : null;
  const visible = tag
    ? entries.filter((entry) => entry.tags?.includes(tag))
    : entries;
  const visibleKey = visible.map((entry) => entry.id).join(" ");
  const internal = maxHeight !== undefined;

  useEffect(() => {
    const container = scroller.current;
    const ol = list.current;
    if (!container || !ol) return;
    let frame = 0;
    const measure = () => {
      frame = 0;
      const items = Array.from(
        ol.querySelectorAll<HTMLElement>(":scope > [data-entry]"),
      );
      if (!items.length) return;
      const top = internal ? container.getBoundingClientRect().top : 0;
      const height = internal ? container.clientHeight : innerHeight;
      // The entry whose top has passed 35% of the view is the current one.
      let index = 0;
      items.forEach((item, itemIndex) => {
        if (item.getBoundingClientRect().top <= top + height * 0.35)
          index = itemIndex;
      });
      if (
        internal &&
        container.scrollTop + container.clientHeight >=
          container.scrollHeight - 2
      )
        index = items.length - 1;
      const center = (item: HTMLElement) => {
        const dot = item.querySelector<HTMLElement>(".is-changelog-dot")!;
        return {
          x: item.offsetLeft + dot.offsetLeft + dot.offsetWidth / 2,
          y: item.offsetTop + dot.offsetTop + dot.offsetHeight / 2,
        };
      };
      const first = center(items[0]);
      const last = center(items[items.length - 1]);
      const now = center(items[index]);
      setCurrent(items[index].dataset.entry);
      setRail((previous) => {
        const next = {
          left: first.x,
          top: first.y,
          height: last.y - first.y,
          progress: now.y - first.y,
        };
        return previous &&
          (Object.keys(next) as (keyof Rail)[]).every(
            (key) => previous[key] === next[key],
          )
          ? previous
          : next;
      });
    };
    const schedule = () => {
      if (!frame) frame = requestAnimationFrame(measure);
    };
    const target = internal ? container : window;
    target.addEventListener("scroll", schedule, { passive: true });
    window.addEventListener("resize", schedule);
    const observer = new ResizeObserver(schedule);
    observer.observe(ol);
    schedule();
    return () => {
      cancelAnimationFrame(frame);
      target.removeEventListener("scroll", schedule);
      window.removeEventListener("resize", schedule);
      observer.disconnect();
    };
  }, [internal, visibleKey]);

  function choose(next: string | null) {
    if (filter === undefined) setInternalFilter(next);
    onFilterChange?.(next);
  }

  function toggle(id: string) {
    setExpanded((previous) => {
      const next = new Set(previous);
      if (next.has(id)) next.delete(id);
      else next.add(id);
      return next;
    });
  }

  const dates = new Intl.DateTimeFormat(locale, {
    year: "numeric",
    month: "short",
    day: "numeric",
    timeZone: "UTC",
  });
  function formatDate(date: string) {
    const parsed = new Date(date);
    return Number.isNaN(parsed.getTime()) ? date : dates.format(parsed);
  }

  if (!entries.length) return null;
  return (
    <section
      className={`is-changelog ${className}`}
      aria-label={label}
      data-reduced-motion={reducedMotion || undefined}
    >
      {filters && tags.length > 0 && (
        <div
          className="is-changelog-filters"
          role="group"
          aria-label="Filter updates"
        >
          {[null, ...tags].map((option) => (
            <button
              key={option ?? "all"}
              type="button"
              aria-pressed={tag === option}
              onClick={() => choose(option)}
            >
              {option ?? "All"}
              <span>
                {option
                  ? entries.filter((entry) => entry.tags?.includes(option))
                      .length
                  : entries.length}
              </span>
            </button>
          ))}
        </div>
      )}
      <div
        className="is-changelog-scroll"
        ref={scroller}
        style={internal ? ({ maxHeight } as CSSProperties) : undefined}
        tabIndex={internal ? 0 : undefined}
        role={internal ? "region" : undefined}
        aria-label={internal ? `${label} entries` : undefined}
      >
        <div className="is-changelog-track">
          {rail && (
            <span
              className="is-changelog-rail"
              aria-hidden="true"
              style={{ left: rail.left, top: rail.top, height: rail.height }}
            >
              <span style={{ height: rail.progress }} />
            </span>
          )}
          <ol className="is-changelog-list" ref={list}>
            {visible.map((entry) => {
              const open = expanded.has(entry.id);
              const detailsId = `${uid}-details-${entry.id}`;
              return (
                <li
                  key={entry.id}
                  className="is-changelog-entry"
                  data-entry={entry.id}
                  data-current={entry.id === current || undefined}
                >
                  <div className="is-changelog-meta">
                    <time dateTime={entry.date}>{formatDate(entry.date)}</time>
                    {entry.version && (
                      <span className="is-changelog-version">
                        {entry.version}
                      </span>
                    )}
                  </div>
                  <span className="is-changelog-dot" aria-hidden="true" />
                  <div className="is-changelog-body">
                    <h3>{entry.title}</h3>
                    {entry.tags && entry.tags.length > 0 && (
                      <ul className="is-changelog-tags" role="list">
                        {entry.tags.map((name) => (
                          <li key={name} data-tag={name.toLowerCase()}>
                            {name}
                          </li>
                        ))}
                      </ul>
                    )}
                    {entry.summary && <p>{entry.summary}</p>}
                    {entry.details && (
                      <>
                        <button
                          type="button"
                          className="is-changelog-toggle"
                          aria-expanded={open}
                          aria-controls={detailsId}
                          onClick={() => toggle(entry.id)}
                        >
                          {open ? "Hide details" : "Show details"}
                          <span className="is-changelog-sr">
                            {" "}
                            for {entry.title}
                          </span>
                          <svg viewBox="0 0 16 16" aria-hidden="true">
                            <path d="m4 6 4 4 4-4" />
                          </svg>
                        </button>
                        <div
                          className="is-changelog-details"
                          id={detailsId}
                          data-open={open}
                          inert={!open}
                        >
                          <div>{entry.details}</div>
                        </div>
                      </>
                    )}
                  </div>
                </li>
              );
            })}
          </ol>
        </div>
      </div>
      <p className="is-changelog-sr" role="status">
        {tag
          ? `Showing ${visible.length} of ${entries.length} updates tagged ${tag}.`
          : `Showing all ${entries.length} updates.`}
      </p>
    </section>
  );
}
changelog-timeline.css
.is-changelog {
  --changelog-surface: var(--surface, #181d25);
  --changelog-text: var(--text, #f0f3f8);
  --changelog-muted: var(--muted, #adb7c6);
  --changelog-line: var(--line, #343d4a);
  --changelog-selected: var(--raised, #242a33);
  --changelog-accent: var(--accent, #b2cfff);
  --changelog-meta-width: 116px;
  width: 100%;
  min-width: 0;
  container-type: inline-size;
  color: var(--changelog-text);
}
.is-changelog *,
.is-changelog *::before,
.is-changelog *::after {
  box-sizing: border-box;
}
.is-changelog-filters {
  display: flex;
  flex-wrap: wrap;
  gap: 6px;
  margin-bottom: 22px;
}
.is-changelog-filters button {
  display: inline-flex;
  align-items: center;
  gap: 8px;
  min-height: 34px;
  padding: 0 12px;
  border: 1px solid var(--changelog-line);
  border-radius: 999px;
  background: transparent;
  color: var(--changelog-muted);
  font: inherit;
  font-size: 12px;
  cursor: pointer;
  transition:
    background 160ms,
    border-color 160ms,
    color 160ms;
}
.is-changelog-filters button > span {
  color: var(--changelog-muted);
  font:
    10px ui-monospace,
    monospace;
}
.is-changelog-filters button[aria-pressed="true"] {
  border-color: color-mix(in srgb, var(--changelog-accent) 60%, transparent);
  background: var(--changelog-selected);
  color: var(--changelog-text);
}
.is-changelog-filters button:focus-visible,
.is-changelog-toggle:focus-visible,
.is-changelog-scroll:focus-visible {
  outline: 2px solid var(--changelog-accent);
  outline-offset: 2px;
}
.is-changelog-scroll {
  overflow-y: auto;
  overscroll-behavior: contain;
  border-radius: 6px;
}
.is-changelog-track {
  position: relative;
}
.is-changelog-list {
  display: grid;
  gap: 8px;
  margin: 0;
  padding: 0;
  list-style: none;
}
.is-changelog-rail {
  position: absolute;
  width: 2px;
  margin-left: -1px;
  border-radius: 2px;
  background: var(--changelog-line);
  pointer-events: none;
}
.is-changelog-rail > span {
  display: block;
  width: 100%;
  border-radius: inherit;
  background: var(--changelog-accent);
  transition: height 320ms cubic-bezier(0.22, 1, 0.36, 1);
}
.is-changelog-entry {
  position: relative;
  display: grid;
  grid-template-columns: var(--changelog-meta-width) 28px minmax(0, 1fr);
  align-items: start;
  column-gap: 14px;
  padding: 10px 0 18px;
}
.is-changelog-meta {
  display: grid;
  justify-items: end;
  gap: 6px;
  padding-top: 3px;
  color: var(--changelog-muted);
  font-size: 12px;
  text-align: right;
}
.is-changelog-version {
  padding: 2px 7px;
  border: 1px solid var(--changelog-line);
  border-radius: 5px;
  font:
    10px ui-monospace,
    monospace;
}
.is-changelog-dot {
  position: relative;
  z-index: 1;
  justify-self: center;
  width: 12px;
  height: 12px;
  margin-top: 5px;
  border: 2px solid var(--changelog-line);
  border-radius: 50%;
  background: var(--changelog-surface);
  transition:
    border-color 220ms,
    box-shadow 220ms;
}
.is-changelog-entry[data-current] .is-changelog-dot {
  border-color: var(--changelog-accent);
  box-shadow: 0 0 0 5px
    color-mix(in srgb, var(--changelog-accent) 18%, transparent);
}
.is-changelog-body {
  min-width: 0;
}
.is-changelog-body h3 {
  margin: 0;
  font-size: 16px;
  font-weight: 600;
  line-height: 1.35;
}
.is-changelog-body > p {
  margin: 8px 0 0;
  color: var(--changelog-muted);
  font-size: 13px;
  line-height: 1.6;
}
.is-changelog-tags {
  display: flex;
  flex-wrap: wrap;
  gap: 5px;
  margin: 8px 0 0;
  padding: 0;
  list-style: none;
}
.is-changelog-tags li {
  padding: 2px 8px;
  border-radius: 999px;
  background: var(--changelog-selected);
  color: var(--changelog-muted);
  font-size: 11px;
}
.is-changelog-toggle {
  display: inline-flex;
  align-items: center;
  gap: 6px;
  min-height: 32px;
  margin-top: 8px;
  padding: 0;
  border: 0;
  background: transparent;
  color: var(--changelog-accent);
  font: inherit;
  font-size: 12px;
  cursor: pointer;
}
.is-changelog-toggle svg {
  width: 14px;
  height: 14px;
  fill: none;
  stroke: currentColor;
  stroke-width: 1.8;
  stroke-linecap: round;
  stroke-linejoin: round;
  transition: transform 220ms;
}
.is-changelog-toggle[aria-expanded="true"] svg {
  transform: rotate(180deg);
}
.is-changelog-details {
  display: grid;
  grid-template-rows: 0fr;
  transition: grid-template-rows 280ms cubic-bezier(0.22, 1, 0.36, 1);
}
.is-changelog-details[data-open="true"] {
  grid-template-rows: 1fr;
}
.is-changelog-details > div {
  min-height: 0;
  overflow: hidden;
  color: var(--changelog-muted);
  font-size: 13px;
  line-height: 1.6;
}
.is-changelog-details > div > :first-child {
  margin-top: 6px;
}
.is-changelog-details > div > :last-child {
  margin-bottom: 0;
}
.is-changelog-sr {
  position: absolute;
  width: 1px;
  height: 1px;
  margin: -1px;
  overflow: hidden;
  clip-path: inset(50%);
  white-space: nowrap;
}
@container (max-width: 520px) {
  .is-changelog-entry {
    grid-template-columns: 24px minmax(0, 1fr);
    grid-template-areas:
      "dot meta"
      ". body";
    column-gap: 12px;
    row-gap: 6px;
  }
  .is-changelog-dot {
    grid-area: dot;
    margin-top: 3px;
  }
  .is-changelog-meta {
    grid-area: meta;
    display: flex;
    align-items: center;
    gap: 8px;
    padding-top: 0;
    text-align: left;
  }
  .is-changelog-body {
    grid-area: body;
  }
}
.is-changelog[data-reduced-motion] .is-changelog-rail > span,
.is-changelog[data-reduced-motion] .is-changelog-dot,
.is-changelog[data-reduced-motion] .is-changelog-details,
.is-changelog[data-reduced-motion] .is-changelog-toggle svg {
  transition: none;
}
@media (prefers-reduced-motion: reduce) {
  .is-changelog .is-changelog-rail > span,
  .is-changelog .is-changelog-dot,
  .is-changelog .is-changelog-details,
  .is-changelog .is-changelog-toggle svg {
    transition: none;
  }
}