Format elapsed

Free · MIT

A measured span of time in the locale: "4.2s" under ten seconds, "42s" under a minute, then "2m 5s". Rounded down, so it never reads longer than what was measured. In a component, pass useFormat() from LocaleProvider. This module has no "use client", so a server component or a server-side replay can call it too, with a format of its own: formatElapsed(ms, { tag: "en-GB", number: (n, o) => new Intl.NumberFormat("en-GB", o).format(n) }).

Markdown

Version 5.2.0· other versions

This page is for 5.2.0, the current release. An earlier release’s page is the Markdown that release published, so the docs match the version you have installed (candor-lock.json records it).

Not in the docs of 1.3.0, 1.4.0, 1.5.0, 1.5.1, 1.6.0, 1.7.0, 1.8.0, 1.8.1, 1.9.0, 1.9.1, 2.0.0, 2.1.0, 2.2.0, 2.3.0, 2.4.0, 2.5.0, 2.5.1, 2.6.0, 2.6.1, 2.6.2, 2.7.0 and 2.8.0: the page came later, or had another name then.

Docs pages weren’t kept for 1.0.0, 1.0.1, 1.1.0, 1.1.1, 1.2.0 and 1.2.1: they are kept from 1.3.0 on, and before that only llms.txt was published.

Preview

Install

With the Candor CLI

Open the starter in StackBlitz

Opens the free starter app in StackBlitz, in your browser, on stackblitz.com. Format elapsed isn’t added for you: run npx candor-ui add format-elapsed in its terminal. The starter’s agent needs an Anthropic API key to chat; without one it shows the components only.

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/format-elapsed

Brings in: tokens

Usage

TSX · The example above

"use client"

import { useFormat } from "@/components/candor/locale"
import { formatElapsed } from "@/lib/candor/format-elapsed"

// Measured spans, as a run's timings report them. On the server, pass a format of your own instead of useFormat().
const spans = [
  { label: "Read the ticket", ms: 4_290 },
  { label: "Searched the help centre", ms: 42_900 },
  { label: "Drafted the reply", ms: 125_000 },
]

export default function Example() {
  const format = useFormat()
  return (
    <dl className="grid max-w-sm grid-cols-[1fr_auto] gap-x-6 gap-y-1 text-sm">
      {spans.map((s) => (
        <div key={s.label} className="contents">
          <dt className="text-muted-foreground">{s.label}</dt>
          <dd className="text-end tabular-nums">{formatElapsed(s.ms, format)}</dd>
        </div>
      ))}
    </dl>
  )
}

Functions

formatElapsed(ms: number, format: ElapsedFormat)

Types

ElapsedFormat: How a measured span reads: the locale it's in and its number format, as LocaleProvider's `useFormat()` gives them.; { /** The BCP 47 tag the list of units is joined in; undefined is the runtime's own locale. */ tag: string | undefined; /** A number in the locale, with Intl.NumberFormat's options. */ number: (n: number, options?: Intl.NumberFormatOptions) => string; }

Types from other items

The props above take these. Each is defined by another item; import it from the path shown.

NumberFormat from @/components/candor/scale: Writes a number in full, in the locale; charts pass `useFormat().number` so server and browser agree.; (n: number, options?: Intl.NumberFormatOptions) => string