Skip to content
Tier

Money

Pro

An amount of money, written in the locale: tabular digits, the currency's symbol where the locale puts it, and the figure in its own isolate so it keeps its order in a right-to-left page. It never animates: a new amount replaces the old one in place, with no count or crossfade, so the figure on screen is always the one given.

Decimals follow formatMoney: a whole amount without them ("$20") unless decimals="always" ("$20.00"; "¥20" in a currency without them), and a fraction never rounded ("$0.0042" stays). An amount that isn't known (null, or a value that isn't a finite number) reads "Not measured", never "$0".

With low and high it is an estimate's range, "about $0.41–$0.99": each end goes to the currency's usual decimals, the low end rounded down and the high end up, so it never claims more precision than an estimate has. When either end has a fraction, both are written with the currency's decimals ("about $12.30–$20.00"), so the two ends read alike. A low end above zero but under the smallest unit gives "up to $0.50", and a range wholly under it "under $0.01". A negative end keeps its sign and is rounded outward too ("about -$0.01–$0.20"). estimated adds a visible "est." after the figure, and screen readers hear "estimated".

Markdown

Preview

Loading the preview

Install

With the Candor CLI

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

Brings in: locale, ops, tokens, utils

Usage

TSX · The example above
"use client"

import { Money } from "@/components/candor/money"

export default function Example() {
  return (
    <dl className="grid max-w-sm grid-cols-[auto_1fr] gap-x-6 gap-y-2 text-sm">
      <dt className="text-muted-foreground">Spent this round</dt>
      <dd>
        <Money amount={7.36} decimals="always" />
      </dd>
      <dt className="text-muted-foreground">Cap</dt>
      <dd>
        <Money amount={25} decimals="always" />
      </dd>
      <dt className="text-muted-foreground">Next round</dt>
      <dd>
        <Money low={4.12} high={9.87} decimals="always" estimated />
      </dd>
      <dt className="text-muted-foreground">Last month</dt>
      <dd>
        <Money amount={null} />
      </dd>
    </dl>
  )
}

<Money>

PropTypeDefaultDescription
amountnumber | null | undefined—The amount, in `currency`. `null` (or left out, without `low` and `high`) reads as not measured, never as zero.
lownumber | undefined—The low end of an estimate's range. With `high`, the range is shown in place of `amount`, rounded outward.
highnumber | undefined—The high end of an estimate's range. With `low`, the range is shown in place of `amount`, rounded outward.
currencystring | undefined"USD"The ISO 4217 code the amount is in, e.g. `"EUR"`. Defaults to `"USD"`. The symbol and its place come from the locale; a code the browser doesn't know is written after the number.
decimals"auto" | "always" | undefined"auto"`"auto"` (the default): a whole amount without decimals ("$20"). `"always"`: at least the currency's usual decimals ("$20.00", "¥20"). Either way an amount with more decimals keeps them.
estimatedboolean | undefinedfalseThe figure is an estimate, not a measured charge: a visible "est." follows it, and screen readers hear "estimated".
classNamestring | undefined—Classes for the figure, merged with Candor's.

Strings

The fixed words, in English by default. Change any of them under money in <LocaleProvider strings={{ … }}>; the table is exported as moneyStrings.

KeyEnglish
notMeasuredNot measured
rangeabout {low}–{high}
underunder {amount}
upToup to {high}
estimatedMarkest.
estimatedestimated
withMark{amount} {mark}