# ngx-currency

> A very simple currency mask directive that allows using a number attribute with the ngModel.

Latest version **19.0.0** (published 2025-01-06) · MIT license · 0 weekly downloads

## Install

```sh
npm install ngx-currency
pnpm add ngx-currency
yarn add ngx-currency
bun add ngx-currency
```

## Health

**Score 35/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 19.0.0 |
| Published | 2025-01-06 |
| First published | 2017-09-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 85.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 249 |
| Author | Neri Bez Fontana |
| Maintainers | nbfontana |
| Keywords | angular, currency, mask, model, money, ngx, number |

## Links

- npm: https://www.npmjs.com/package/ngx-currency
- Repository: https://github.com/nbfontana/ngx-currency
- Homepage: https://github.com/nbfontana/ngx-currency#readme
- Issues: https://github.com/nbfontana/ngx-currency/issues
- npm.io page: https://npm.io/package/ngx-currency

## Dependencies (1)

- [tslib](https://npm.io/package/tslib.md) ^2.5.0

## Alternatives

- [random-seedable](https://npm.io/package/random-seedable.md) — 27.9K weekly downloads
- [n2words](https://npm.io/package/n2words.md) — 22.2K weekly downloads
- [@stdlib/math-base-special-factorialln](https://npm.io/package/@stdlib/math-base-special-factorialln.md) — 5.7K weekly downloads
- [@stdlib/math-base-special-abs2](https://npm.io/package/@stdlib/math-base-special-abs2.md) — 1.7K weekly downloads
- [commons-math-interpolation](https://npm.io/package/commons-math-interpolation.md) — 1.4K weekly downloads

## Recent versions

- 19.0.0 (latest) — 2025-01-06
- 18.0.0 — 2024-06-04
- 17.0.0 — 2024-01-11
- 4.0.0 — 2023-07-14
- 3.0.0 — 2022-11-30
- 2.5.3 — 2021-09-20
- 2.5.2 — 2020-11-10
- 2.5.1 — 2020-08-05
- 2.4.1 — 2020-08-05
- 2.4.0 — 2020-08-05
- 2.3.3 — 2020-04-22
- 2.3.2 — 2020-04-17
- 2.3.1 — 2020-04-15
- 2.2.4 — 2020-04-15
- 2.2.3 — 2020-04-14
- … 14 more at https://npm.io/package/ngx-currency/versions

## README

# ngx-currency

[![npm version](https://badge.fury.io/js/ngx-currency.png)](http://badge.fury.io/js/ngx-currency)
[![GitHub issues](https://img.shields.io/github/issues/nbfontana/ngx-currency.png)](https://github.com/nbfontana/ngx-currency/issues)
[![GitHub stars](https://img.shields.io/github/stars/nbfontana/ngx-currency.png)](https://github.com/nbfontana/ngx-currency/stargazers)
[![GitHub license](https://img.shields.io/badge/license-MIT-blue.png)](https://raw.githubusercontent.com/nbfontana/ngx-currency/master/LICENSE)

## Demo

https://nbfontana.github.io/ngx-currency/

## Table of contents

- [Getting Started](#getting-started)
- [Documentation](https://nbfontana.github.io/ngx-currency/docs/)
- [Development](#development)
- [License](#license)

## Getting Started

### Installing and Importing

Install the package by command:

```sh
npm install ngx-currency --save
```

Import the directive

```ts
import { NgxCurrencyDirective } from "ngx-currency";

@Component({
  selector: "app-root",
  templateUrl: "./app.component.html",
  imports: [NgxCurrencyDirective],
})
export class AppComponent {}
```

### Using

```html
<input type="text" inputmode="decimal" currencyMask formControlName="value" />
```

- `ngModel` An attribute of type number. If is displayed `'$ 25.63'`, the attribute will be `'25.63'`.

### Options

You can set options...

```html
<!-- example for pt-BR money -->
<input [currencyMask]="{ prefix: 'R$ ', thousands: '.', decimal: ',' }" formControlName="value" />
```

Available options:

- `align` - Text alignment in input. (default: `right`)
- `allowNegative` - If `true` can input negative values. (default: `true`)
- `decimal` - Separator of decimals (default: `'.'`)
- `precision` - Number of decimal places (default: `2`)
- `prefix` - Money prefix (default: `'$ '`)
- `suffix` - Money suffix (default: `''`)
- `thousands` - Separator of thousands (default: `','`)
- `nullable` - when true, the value of the clean field will be `null`, when false the value will be `0`
- `min` - The minimum value (default: `undefined`)
- `max` - The maximum value (default: `undefined`)
- `inputMode` - Determines how to handle numbers as the user types them (default: `Financial`)

Input Modes:

- `Financial` - Numbers start at the highest precision decimal. Typing a number shifts numbers left.
  The decimal character is ignored. Most cash registers work this way. For example:
  - Typing `'12'` results in `'0.12'`
  - Typing `'1234'` results in `'12.34'`
  - Typing `'1.234'` results in `'12.34'`
- `Natural` - Numbers start to the left of the decimal. Typing a number to the left of the decimal shifts
  numbers left; typing to the right of the decimal replaces the next number. Most text inputs
  and spreadsheets work this way. For example:
  - Typing `'1234'` results in `'1234'`
  - Typing `'1.234'` results in `'1.23'`
  - Typing `'12.34'` results in `'12.34'`
  - Typing `'123.4'` results in `'123.40'`

You can also set options globally...

```ts
import { provideEnvironmentNgxCurrency, NgxCurrencyInputMode } from 'ngx-currency';

bootstrapApplication(AppComponent, {
  providers: [
    ...
    provideEnvironmentNgxCurrency({
      align: "right",
      allowNegative: true,
      allowZero: true,
      decimal: ",",
      precision: 2,
      prefix: "R$ ",
      suffix: "",
      thousands: ".",
      nullable: true,
      min: null,
      max: null,
      inputMode: NgxCurrencyInputMode.Financial,
    }),
    ...
  ],
}).catch((err) => console.error(err));
```

## Development

### Prepare your environment

- Install [Node.js](http://nodejs.org/) and NPM
- Install local dev dependencies: `npm install` while current directory is this repo

### Development server

To start a local development server, run:

```bash
npm start
```

### Building

To build the library run:

```bash
npm run build:lib
```

### Testing

To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:

```bash
npm test
```

When running in the Chrome browser, you can set code breakpoints to debug tests using these instructions:

- From the main Karma browser page, click the `Debug` button to open the debug window
- Press `ctrl + shift + i` to open Chrome developer tools
- Press `ctrl + p` to search for a file to debug
- Enter a file name like `input.handler.ts` and click the file
- Within the file, click on a row number to set a breakpoint
- Refresh the browser window to re-run tests and stop on the breakpoint

## License

MIT @ Neri Bez Fontana

---
_Source: https://npm.io/package/ngx-currency · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._