React-forex-price NPM

react-forex-price

circleci passing

An automatic currency conversion component for React, perfect as a drop-in replacement for displaying monetary values in your users' home currency.

✨ Try it for yourself with this demo ✨

Note: This component is intended for displaying estimated prices — you should not transact based on the values received from this component.

Features

Accurate. Daily foreign exchange rates from the European Central Bank, for free.
Easy. Dead-simple usage. No API key required.
Efficient. Multiple instances incur only one network request per user per day, cached automatically.
Formatted. Locale-aware, so prices are displayed the way users expect.
Worldwide. 32 currencies supported.
Compatible. Works in all major browsers, React 0.14 and up, 8.9kB minified, 3.5kB minified + gzipped.

Installation

Add it to your project:

yarn add react-forex-price

(Note: You'll need a promise polyfill if you're not using one already for this to work in browsers that don't support promises natively. I recommend promise-polyfill.)

Import it anywhere:

import Price from 'react-forex-price';

Usage

If your base currency is USD, all you need to do is plug your values into the amount prop as a number.

<p>I bought a dress for <Price amount={123.45} />.</p>

Props

Only the amount prop is required.

Prop	Description
`amount`	(Number. Required. No default value) The amount you are converting.
`baseCurrency`	(String. Optional. Default value: `USD`) The currency you are converting from. This should be the same value for all instances so that prices are normalized.
`displayCurrency`	(String. Optional. Default value: Determined by user's locale, fallback to `USD`) The currency you are converting to. The user's browser language (i.e. `navigator.language`) is consulted to determine a default value. Note: If you already know the user's preferred currency (based on data you collect), it is recommended to supply it.
`dropCents`	(Boolean. Optional. Default value: `false`) Whether to omit digits after the decimal point, if they exist. See Rounding.
`rounding`	(Function. Optional. Default value: `Math.round`) Rounding function. See Rounding.
`unwrap`	(Boolean. Optional. Default value: `false`) Whether to unwrap the outputted `<span>` element. See Output.

Data

Exchange rate data comes from Fixer, an open-source, simple, and lightweight API for current and historical foreign exchange (forex) rates published by the European Central Bank.

The Fixer API will only be consulted once per user per unique base currency per day, no matter how many Price instances you have per page.

The data is cached via localStorage if available, falling back to memory.

If the API cannot be reached, the amount is displayed in the base currency (formatted based on user locale, but not converted).

Supported currencies

The following currencies are currently supported:

AUD: Australian dollar
BGN: Bulgarian lev
BRL: Brazilian real
CAD: Canadian dollar
CHF: Swiss franc
CNY: Chinese yuan renminbi
CZK: Czech koruna
DKK: Danish krone
EUR: Euro
GBP: Pound sterling
HKD: Hong Kong dollar
HRK: Croatian kuna
HUF: Hungarian forint
IDR: Indonesian rupiah
ILS: Israeli shekel
INR: Indian rupee
ISK: Icelandic krona
JPY: Japanese yen
KRW: South Korean won
MXN: Mexican peso
MYR: Malaysian ringgit
NOK: Norwegian krone
NZD: New Zealand dollar
PHP: Philippine piso
PLN: Polish zloty
RON: Romanian leu
RUB: Russian rouble
SEK: Swedish krona
SGD: Singapore dollar
THB: Thai baht
TRY: Turkish lira
USD: US dollar

There may be plans to support other currencies in the future. There are no plans to support cryptocurrencies.

Examples

If displayCurrency is not specified, the display currency is estimated by the user's locale. For <Price amount={8675.309} />, a user in the USA would see a value of approximately "$8,675.31", and a user in Germany would see a value of approximately "€6.944,67".

If displayCurrency is specified, then the conversion is forced. For <Price amount={8675.309} displayCurrency="EUR" />, a user in the USA would see a value of approximately "€6,944.67", and a user in Germany would see a value of approximately "€6.944,67" (notice thousands separator and decimal point).

Rounding

For e.g. the en-US locale,

<Price amount={8675.309} rounding={Math.floor} /> results in $8,675.30
<Price amount={8675.309} rounding={Math.floor} dropCents /> results in $8,675
<Price amount={8675.309} rounding={Math.ceil} /> results in $8,675.31
<Price amount={8675.309} rounding={Math.ceil} dropCents /> results in $8,676

Output

By default, prices are wrapped in a <span> element. For example,

<Price amount={123.45} displayCurrency="EUR" />

translates to

<span title="$123.45 USD">€99.08</span>

If you would like to simply return an unwrapped string, pass the unwrap prop. That makes

<Price amount={123.45} displayCurrency="EUR" unwrap />

translate to

€99.08

Testing

Run yarn lint to lint with eslint
Run yarn flow for static type analysis with flow
Run yarn test to run unit tests with jest
Run yarn test:full for all of the above

All tests are run on each pull request via CircleCI.

Contributing

Want to improve something? Feel free to file an issue or open a pull request 😁

currency conversion convert format price cost exchange rate foreign exchange forex money

local-storage unfetch

@infinitebrahmanuniverse/nolb-react-fo @everything-registry/sub-chunk-2556 @zalastax/nolb-react-fo

1.0.0

6 years ago