@cuppy/core

Cuppy

Cuppy is a zero-dependency TypeScript library for declaratively formatting monetary values across your webpage. It supports automatic adjustment of historical currency amounts for inflation based on the Consumer Price Index. (“Cuppy” is how “CPI” would be pronounced if economics was any fun.)

Usage

Basic usage

Formatting

To mark an element as a Cuppy, add the data-cuppy attribute to it and provide the monetary value as the element’s text content or using the data-value attribute:

<!-- Via innerText -->
<span data-cuppy>25400000000</span>

<!-- Via data-value -->
<span data-cuppy data-value="25400000000"></span>

<!-- Using underscores to separate thousands -->
<span data-cuppy>25_400_000_000</span>
<span data-cuppy data-value="25_400_000_000"></span>

Then in your JavaScript, call the cuppy function to format all Cuppies on the page:

import cuppy from "@cuppy/core";

cuppy();

This will format the Cuppy using the default options for the user’s preferred locale.

Inflation adjustment

To adjust the value for inflation, you must install a dataset for the Consumer Price Index. For example, the @cuppy/cpi-u package provides data for the United States Consumer Price Index for All Urban Consumers (CPI-U) all the way back to 1913. You can install it like this:

npm i @cuppy/cpi-u

and then load it in your JavaScript:

import cuppy from "@cuppy/core";
import cpiU from "@cuppy/cpi-u";

cuppy.dataset(cpiU);

cuppy();

Then in your HTML, set the data-from and optionally data-to attributes to the years you want to adjust between and voilà!

<span data-cuppy data-from="1969" data-to="2020">25400000000</span>
<!-- $179B -->

Advanced usage

You can customize almost every aspect of the formatting by setting attributes on the element:

<span
  data-cuppy
  data-from="1969"
  data-to="2020"
  data-hint="to"
  data-hint-display="inline"
  data-year-display="always"
  data-hint-year-display="ifFallback"
  data-number-style="compactShort"
  data-currency-style="name"
  data-sign-display="always"
  data-use-grouping
  data-precision-mode="decimalPlaces"
  data-min-digits="4"
  data-max-digits="5"
  data-inflation-dataset="cpiU"
  data-locale="en-NZ"
>
  25_400_000_000
</span>

Cuppy uses Intl.NumberFormat under the hood, so you can use any of the options supported by that API. See the MDN documentation for more information.

Attribute	Default value	Description
from	The current year	The year to adjust the value from.
to	The current year	The year to adjust the value to. Either this or from must be set for inflation adjustment to occur.
hint	"none"	The hint to display next to the value. Can be "to" (adjusted value as hint), "from" (source value as hint), or "none" (adjusted value only).
hint-display	"tooltip"	The display mode for the hint. Can be "inline" or "tooltip".
year-display	"ifFallback"	The display mode for the year. Can be "always", "exceptCurrent", "ifFallback", or "never".
hint-year-display	"always"	The display mode for the year in the hint. Can be "always", "exceptCurrent", "ifFallback", or "never".
number-style	"compactLong"	The number style to use. Can be "standard", "scientific", "engineering", "compactShort", or "compactLong". Combines the notation and compactDisplay options of Intl.NumberFormat.
currency-style	"symbol"	The currency style to use. Can be "symbol", "narrowSymbol", "code", or "name". Corresponds to currencyDisplay in Intl.NumberFormat.
sign-display	"auto"	The display mode for the sign. Can be "auto", "always", "exceptZero", or "never".
use-grouping	Same as in Intl.NumberFormat	Whether to use grouping separators. Any non-null value other than "false" (including an empty string) will be treated as true.
precision-mode	"significantDigits"	The precision mode to use. Can be "significantDigits" or "decimalPlaces".
min-digits	Same as in Intl.NumberFormat	The minimum number of digits to display. Equivalent to minimumFractionDigits if precision-mode is "decimalPlaces" and minimumSignificantDigits if precision-mode is "significantDigits".
max-digits	Same as in Intl.NumberFormat	The maximum number of digits to display. Equivalent to maximumFractionDigits if precision-mode is "decimalPlaces" and maximumSignificantDigits if precision-mode is "significantDigits".
inflation-dataset	"cpiU"	The name of the inflation dataset to use.
locale	document.documentElement.lang	The locale to use for formatting. Must be a valid BCP 47 language tag.

You can also configure the default values for these options globally:

import cuppy from "@cuppy/core";
import cpiU from "@cuppy/cpi-u";

// Set global defaults
cuppy.options.hint = "to";
cuppy.options.currencyStyle = "code";
cuppy.options.numberStyle = "compactShort";
cuppy.options.useGrouping = false;
cuppy.options.maxDigits = 3;

// Load inflation dataset
cuppy.dataset(cpiU);

// Format all Cuppies on the page!
cuppy();

Note that per-element attributes will override global defaults.

You can modify how the year and hint are displayed by setting the yearFormatter and inlineHintFormatter options, respectively:

cuppy.options.yearFormatter = (value, year) => `${value} in ${year}`;
cuppy.options.inlineHintFormatter = (value, hint) => `${value} (${hint})`;

This will result in the following output:

<span
  data-cuppy
  data-from="1969"
  data-hint-display="inline"
  data-year-display="always"
  data-hint-year-display="ifFallback"
  data-currency-style="name"
  data-min-digits="4"
  data-max-digits="5"
>
  25_400_000_000
</span>
<!-- 25.40 billion US dollars in 1969 (210.88 billion US dollars in 2023) -->

Browser support

Cuppy supports all modern browsers supporting ES6 and above. The availability of some options may vary depending on the browser. See the MDN documentation for more information.

Contributing

If you like Cuppy and want to help make it better, please consider contributing! It can be as simple as opening an issue to report a bug or suggest an improvement, or as involved as implementing a new feature or fixing a bug yourself. For more information, see CONTRIBUTING.md.

License

Cuppy is licensed under the MIT License.