1 | # ![geld](media/logo.png)
|
2 |
|
3 | > geld is a minimal currency formatter.
|
4 |
|
5 | ![Update Status](https://img.shields.io/david/dev/dreamseer/geld.svg)
|
6 | [![Build Status](https://travis-ci.org/Dreamseer/geld.svg?branch=main)](https://travis-ci.org/Dreamseer/geld)
|
7 | [![Coverage Status](https://coveralls.io/repos/github/Dreamseer/geld/badge.svg?branch=main)](https://coveralls.io/github/Dreamseer/geld?branch=main)
|
8 | [![Install size](https://packagephobia.now.sh/badge?p=geld)](https://packagephobia.now.sh/result?p=geld)
|
9 | [![XO code style](https://img.shields.io/badge/code_style-XO-5ed9c7.svg)](https://github.com/sindresorhus/xo)
|
10 | [![Flow](https://img.shields.io/npm/types/geld)](https://flow.org/)
|
11 | [![MIT license](https://img.shields.io/github/license/dreamseer/geld.svg)](https://github.com/Dreamseer/geld/blob/main/LICENSE.md)
|
12 |
|
13 | ## Install
|
14 |
|
15 | Using [npm](https://www.npmjs.com/get-npm):
|
16 |
|
17 | ```bash
|
18 | npm install geld --save
|
19 | ```
|
20 |
|
21 | Using [yarn](https://yarnpkg.com/):
|
22 |
|
23 | ```bash
|
24 | yarn add geld
|
25 | ```
|
26 |
|
27 | ## Usage
|
28 |
|
29 | ```js
|
30 | const geld = require('geld');
|
31 |
|
32 | const price1 = geld(42.23);
|
33 | console.log(price1); // => '42,23 €'
|
34 |
|
35 | const price2 = geld(42, { zeroDecimals: '–' });
|
36 | console.log(price2); // => '42,– €'
|
37 | ```
|
38 |
|
39 | ## API
|
40 |
|
41 | ### geld(value, [options])
|
42 |
|
43 | #### value
|
44 |
|
45 | Type: `number` or `string`
|
46 |
|
47 | Required value to format.
|
48 |
|
49 | #### options.currency
|
50 |
|
51 | Type: `string`
|
52 |
|
53 | Currency symbol to use.
|
54 | Default: `'€'`
|
55 |
|
56 | #### options.currencyPosition
|
57 |
|
58 | Type: `string`
|
59 |
|
60 | Position of the currency symbol, either `'before'` or `'after'` the formatted value.
|
61 | Default: `'after'`
|
62 |
|
63 | #### options.decimals
|
64 |
|
65 | Type: `number`
|
66 |
|
67 | Amount of decimals.
|
68 | Default: `2`
|
69 |
|
70 | #### options.decimalSeparator
|
71 |
|
72 | Type: `string`
|
73 |
|
74 | Character for decimal separation, e.g. in `1,23`.
|
75 | Default: `','`
|
76 |
|
77 | #### options.orderSeparator
|
78 |
|
79 | Type: `string`
|
80 |
|
81 | Character for order separation, e.g. in `1.000.000`.
|
82 | Default: `'.'`
|
83 |
|
84 | #### options.zeroDecimals
|
85 |
|
86 | Type: `string`
|
87 |
|
88 | Character to use as a replacement for zero decimals, e.g. `1,–`.
|
89 | Default: `''`
|
90 |
|
91 | #### options.space
|
92 |
|
93 | Type: `string`
|
94 |
|
95 | Character to use as a spacer between formatted value and currency symbol.
|
96 | Default: `' '` (i.e. `U+00A0 NO-BREAK SPACE`)
|
97 |
|
98 | ## FAQ
|
99 |
|
100 | ### “Why did you set these silly defaults? I prefer X.”
|
101 |
|
102 | Of course geld’s defaults are opinionated:
|
103 | I’m from Germany, thus I set German Euro defaults.
|
104 |
|
105 | ### “How is the name written and pronounced?”
|
106 |
|
107 | geld, not GELD or Geld. Pronounced [/ɡɛlt/](https://en.wiktionary.org/wiki/Geld).
|
108 |
|
109 | ## Related
|
110 |
|
111 | * [geld-cli](https://github.com/dreamseer/geld-cli) is a CLI for geld.
|
112 | * [`Number.toLocaleString()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toLocaleString) provides native currency formatting.
|
113 | * [currency-formatter](https://github.com/smirzaei/currency-formatter) is a more powerful formatter.
|
114 |
|
115 | ## License
|
116 |
|
117 | MIT © [Marc Görtz](https://marcgoertz.de/)
|