@cuppy/core v1.1.0

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.

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.