Format numbers and dates through the library, with an explicit locale

what this catches

why

use this instead

Number.toLocaleString()

• FormattedNumber from @/components/formatted-numberrendering a number in JSX
• formatNumber from @/components/formatted-numbera string is needed — it takes the locale as its second argument
• useFormatNumber from @/components/formatted-numbera string is needed inside a component, with the locale read from the I18nProvider

Number.toLocaleString() for money

• FormattedCurrency from @/components/formatted-numberrendering an amount in JSX
• formatCurrency from @/components/formatted-numbera string is needed — EUR, always two decimals

Date.toLocaleDateString() / new Intl.DateTimeFormat()

• FormattedDate from @/components/formatted-datean absolute date or time — it renders a semantic <time> with a pinned locale and time zone

Relative output ("3 days ago") depends on when it is rendered, so pass `now` when the result has to be identical on the server and in the browser.

CalendarDate.toString() / Time.toString() rendered into JSX

• FormattedDate from @/components/formatted-dateechoing a picker's value back to the reader — the segments above it are localized, so the echo has to be too

A `CalendarDate` has no time of day and a `Time` has no day at all, so formatting either through Intl means choosing both plus a zone. Anchor the value with `toZoned(value, zone)` and pass that same `zone` to FormattedDate: anchoring in the viewer's zone instead puts the echo a day away from the segments for any reader west of the one you format in.

wrong / right

<BarList
  data={pages}
  valueFormatter={(value) => value.toLocaleString()}
  className="w-full max-w-md"
/>

import { formatNumber } from "@/components/formatted-number"

<BarList
  data={pages}
  valueFormatter={(value) => formatNumber(value, "de-DE")}
  className="w-full max-w-md"
/>

<LeaderboardEnd>{player.score.toLocaleString()}</LeaderboardEnd>

import { FormattedNumber } from "@/components/formatted-number"

<LeaderboardEnd>
  <FormattedNumber value={player.score} />
</LeaderboardEnd>

<Description>{value ? value.toString() : "No date selected"}</Description>

import { toZoned } from "@internationalized/date"
import { FormattedDate } from "@/components/formatted-date"

<Description>
  {value ? (
    <FormattedDate
      date={toZoned(value, DISPLAY_TIME_ZONE).toDate()}
      timeZone={DISPLAY_TIME_ZONE}
      dateStyle="medium"
    />
  ) : (
    "No date selected"
  )}
</Description>

how to check this

Add one of these to your project and the rule holds without anyone having to remember it — including the agent writing half the JSX. The exceptions below are already applied, so a documented carve-out will not be reported.

What it will and will not catch: A wrapper of your own is allowed to call Intl: the check skips anything inside a function declaration named format* or use*, which is how a project-level formatter opts out without a suppression. It reads the call, not the locale — `toLocaleString("de-DE")` with an explicit locale is reported too, because the library formatter is still the answer and one place to change it is the reason the rule exists. It matches a construction, so a formatter called without `new` — `Intl.NumberFormat(locale).format(n)` is legal and does the same thing — escapes it entirely; the ripgrep line catches those. `new Intl.DateTimeFormat().resolvedOptions().timeZone` is the known false positive in the other direction; suppress it with `lint/plugin/format-values-through-the-library` and the reason. The `.toString()` half is matched by position and not by type, because GritQL has none: the call has to *be* a JSX expression child — `{value.toString()}`, or a template literal in that same slot — with no JSX attribute and no function boundary between the two. So `key={id.toString()}`, a `valueFormatter` callback, `{rows.map((r) => r.id.toString()).join()}` and a `new URLSearchParams(q).toString()` in a helper are all outside it on purpose, as is `n.toString(16)`, which is a radix conversion rather than a date reaching the DOM. Those are misses, not exceptions: the ripgrep line is deliberately looser than the plugin here and will show you them.

// Format numbers and dates through the library, with an explicit locale
// AUTO-GENERATED from https://ui-lib.quebi.de/api/rules/format-values-through-the-library.json — do not edit by hand.
//
// https://ui-lib.quebi.de/rules/format-values-through-the-library
//
// This file says what the rule is, not where it applies. A plugin listed in
// the top-level `plugins` runs against every file Biome lints, so scope it
// with an `overrides` entry — Biome resolves `includes` against the project
// root, which is the one thing a $filename regex in here could not do:
//
//   {
//     "overrides": [
//       {
//         "includes": [
//           "app/**/*.{tsx,jsx}",
//           "src/**/*.{tsx,jsx}",
//           "!src/components/**",
//           "!components/ui/**"
//         ],
//         "plugins": [
//           "./ui-lib-rules/format-values-through-the-library.grit"
//         ]
//       }
//     ]
//   }

language js;

or {
  `$value.toLocaleDateString($args)`,
  `$value.toLocaleTimeString($args)`,
  `$value.toLocaleString($args)`,
  `new Intl.DateTimeFormat($args)`,
  `new Intl.NumberFormat($args)`,
  `new Intl.RelativeTimeFormat($args)`,
  `$value.toString()` where {
    $value <: within JsxExpressionChild() until or {
      JsxAttributeInitializerClause(),
      JsArrowFunctionExpression(),
      JsFunctionExpression()
    }
  }
} as $call where {
  $call <: not within JsFunctionDeclaration(id = r"^(?:format[A-Z]|use[A-Z]).*"),
  register_diagnostic(
    span = $call,
    message = "This puts a value on the page without the library formatter: a toLocale* call or an Intl construction formats against whatever locale the runtime has, which differs between the prerender and the browser, and a .toString() rendered as JSX text prints the wire format in both. Render <FormattedNumber>, <FormattedCurrency> or <FormattedDate> from @/components/formatted-number and @/components/formatted-date, or call formatNumber(value, locale) / formatCurrency(value, locale) where a string is needed. See https://ui-lib.quebi.de/rules/format-values-through-the-library",
    severity = "error"
  )
}

# format-values-through-the-library — candidates for review
rg -n -g '*.{jsx,tsx}' \
  -g '!src/components/**' \
  -g '!components/ui/**' \
  "\\.toLocale(String|DateString|TimeString)\\(|new Intl\\.(NumberFormat|DateTimeFormat|RelativeTimeFormat)\\(|\\{.*\\.toString\\(\\)"

// biome-ignore lint/plugin/format-values-through-the-library: Asking the platform what it resolved, rather than formatting with it — `new Intl.DateTimeFormat().resolvedOptions().timeZone` is the standard way to read the current time zone and has no library equivalent.

// Between JSX children, where a comment has to be an expression, the same
// line is written {/* biome-ignore … */}.

Enforcing more than this one rule? Take the whole config instead of collecting snippets.

exceptions

Carve-outs are part of the rule, not a way around it. Each one is already an ignore glob in the checks above, so the cases listed here need no disable comment — and a case that is not listed is one to argue for, not to silence.

scope and enforcement

Applies to

• app/**/*.{tsx,jsx}
• src/**/*.{tsx,jsx}

Enforced by

lint