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