react-timeago

react-timeago is a focused React component for displaying relative time (“5 minutes ago”, “in 2 days”) that keeps itself in sync without a page refresh. It wraps a date in a <time> element and schedules its own re-renders on a variable interval — updating every second for recent timestamps and backing off to hourly or weekly ticks as the timestamp ages, so it never over-renders.

Beyond the default English formatter, the library ships with translated strings for more than 70 languages, an opt-in formatter built on the native Intl.RelativeTimeFormat API, and a fully pluggable formatter function for teams that want complete control over the output. At roughly a hundred lines of core logic, it stays intentionally small while covering the corner cases (custom now() for SSR, configurable min/max update periods, arbitrary wrapper components) that hand-rolled “time ago” implementations usually get wrong.

What You Get

• A drop-in <TimeAgo date={...} /> component that renders a live-updating <time> element (or any custom component via the component prop)
• A self-scheduling update loop that ticks every second for fresh timestamps and progressively backs off to minute/hour/week intervals as the timestamp ages, capped by configurable minPeriod/maxPeriod
• Translated formatter strings for 70+ languages via buildFormatter, plus a short-form variant for many locales
• An Intl.RelativeTimeFormat-backed formatter (makeIntlFormatter) for locale-correct output using the browser’s built-in internationalization engine
• A fully pluggable formatter prop so teams can return custom strings or React nodes instead of the default output
• Server-render-safe now() override so the initial render matches between server and client

Common Use Cases

• Showing “posted 3 hours ago” style timestamps under comments, feed items, or notifications that update live as the page stays open
• Displaying last-updated/last-seen indicators (e.g. “last active 5 minutes ago”) in dashboards and admin panels
• Localizing relative timestamps for an international audience using the built-in language strings or the Intl formatter
• Building custom time displays (e.g. “just now”, “yesterday”) by supplying a custom formatter function

Under The Hood

Architecture: The entire library centers on one component, TimeAgo (src/index.js), built with useState/useEffect hooks rather than a class-based timer pattern. On each render it computes the elapsed time between date and the current timeNow state, derives the next update delay from that elapsed time (1s under a minute, 1 minute under an hour, 1 hour under a day, otherwise capped by maxPeriod), and schedules exactly one setTimeout for that delay — clearing it on unmount or when date/live/minPeriod/maxPeriod change. Formatting is delegated to a pluggable formatter function that receives (value, unit, suffix, epochMilliseconds, nextFormatter, now), with defaultFormatter (src/defaultFormatter.js) as the fallback and nextFormatter letting a custom formatter selectively defer back to the default for cases it doesn’t handle. dateParser.js normalizes the three accepted date input shapes (Date object, string, epoch number) into a single Date.

Tech Stack: Written in Flow-typed JavaScript (not TypeScript) with Babel for compilation to two output targets — CommonJS (lib/) and ES modules (es6/) — declared via package.json exports conditions. Type declarations are generated post-build from the Flow annotations via a custom scripts/gen-types.js script (using flow-api-translator) rather than hand-written .d.ts files. The only runtime dependency is react itself as a peer dependency (16–19 supported); everything else (Babel, ESLint with hermes-eslint/Prettier via prettier-plugin-hermes-parser, Rollup for the examples bundle, Jest) is a dev-only tool.

Code Quality: Two Jest test files (__tests__/index.js, __tests__/formatter-value-tests.js, ~160 lines combined) cover the component’s rendering and the value/unit boundary logic (second→minute→hour→day→week→month→year thresholds) using @testing-library/react and a jsdom environment; npm test runs with coverage enabled. The formatter call is wrapped in a try/catch that logs and falls back to defaultFormatter if a custom formatter throws, and an invalid date triggers a console.warn and a null render rather than a crash. Linting is enforced via a fairly strict ESLint config (eslint-plugin-flowtype/ft-flow, import, react-hooks, prettier).