# Brazilian Values V2 [🇧🇷 Trocar para a versão em português](./README.md) [![License](https://badgen.net/github/license/tyagoveras/brazilian-values-v2)](./LICENSE) [![Library minified size](https://badgen.net/bundlephobia/min/brazilian-values-v2)](https://bundlephobia.com/result?p=brazilian-values-v2) [![Library minified + gzipped size](https://badgen.net/bundlephobia/minzip/brazilian-values-v2)](https://bundlephobia.com/result?p=brazilian-values-v2) Validates and formats brazilian values, like money (BRL), CPF, CNPJ, dates etc. > **Note:** This is a fork of the abandoned [brazilian-values](https://github.com/VitorLuizC/brazilian-values) project. Maintained and updated by Tyago Veras. ## Install This module is published under NPM registry, so you can install using any Node.js package manager. ```sh npm install brazilian-values-v2 --save # For Yarn use the command below. yarn add brazilian-values-v2 ``` ### Install from CDN The bundles of this module are also available on [JSDelivr](https://www.jsdelivr.com/) and [UNPKG](https://unpkg.com/) CDNs. > In both you can import just the _bundle_ you want or use default one, UMD. ```html ``` ## Usage `brazilian-values` provides functions to deal with formatting, validating and parsing brazilian values. All those functions could be imported from package. ```js import { isCNPJ, formatToCNPJ } from "brazilian-values-v2"; const value = "12727442000113"; if (!isCNPJ(value)) throw new Error("CNPJ is not valid."); const document = formatToCNPJ(value); //=> '12.727.442/0001-13' ``` ## API
Formatters - [`formatToBRL`](#formatToBRL) - [`formatToCAEPF`](#formatToCAEPF) - [`formatToCapitalized`](#formatToCapitalized) - [`formatToCEP`](#formatToCEP) - [`formatToCNPJ`](#formatToCNPJ) - [`formatToCNPJAlphanumeric`](#formatToCNPJAlphanumeric) - [`formatToCPF`](#formatToCPF) - [`formatToCPFOrCNPJ`](#formatToCPFOrCNPJ) - [`formatToDate`](#formatToDate) - [`formatToDateTime`](#formatToDateTime) - [`formatToList`](#formatToList) - [`formatToNumber`](#formatToNumber) - [`formatToPhone`](#formatToPhone) - [`formatToRG`](#formatToRG) - [`formatToHiddenDigits`](#formatToHiddenDigits)
Parsers - [`parseToArray`](#parseToArray) - [`parseToDate`](#parseToDate) - [`parseToNumber`](#parseToNumber)
Validators - [`isCAEPF`](#isCAEPF) - [`isCEP`](#isCEP) - [`isCNPJ`](#isCNPJ) - [`isCNPJAlphanumeric`](#isCNPJAlphanumeric) - [`isCPF`](#isCPF) - [`isCPFOrCNPJ`](#isCPFOrCNPJ) - [`isDate`](#isDate) - [`isDDD`](#isDDD) - [`isPhone`](#isPhone)
### Formatters #### `formatToBRL` Formats numbers or texts containing numbers to brazilian currency (BRL). ```js formatToBRL(1928.93); //=> 'R$ 1.928,93' formatToBRL("9211928.18203"); //=> 'R$ 9.211.928,18' formatToBRL(-18.49); //=> 'R$ -18,49' ``` #### `formatToCAEPF` Formats a text containing numbers to CAEPF. ```js formatToCAEPF("128781"); //=> '128.781' formatToCAEPF("32284981000150"); //=> '322.849.810/001-50' formatToCAEPF("00.0.000.00.00--00-00"); //=> '000.000.000/000-00' ``` #### `formatToCapitalized` Capitalizes the words in a text, except for words that are set to be uppercase or lowercase. > The first word of the text will not be lowercase even if set to. ```js formatToCapitalized("SERVIDOR PÚBLICO MUNICIPAL"); //=> 'Servidor Público Municipal' formatToCapitalized(" os PrimEIROS HOMens da tERra", { wordsToKeepLowerCase: ["os", "da"], }); //=> 'Os Primeiros Homens da Terra' formatToCapitalized("nova tv foi lançada", { wordsToKeepUpperCase: ["tv"], }); //=> 'Nova TV Foi Lançada' formatToCapitalized(" com espaços antes e depois ", { trimTrailingWhiteSpaces: false, }); //=> ' Com Espaços Antes e Depois ' ``` #### `formatToCEP` Formats a text containing numbers to CEP. ```js formatToCEP("15998030"); //=> '15998-030' formatToCEP("02999"); //=> '02999' ``` #### `formatToCNPJ` Formats a text containing numbers to numeric CNPJ. > For formatting alphanumeric CNPJs, use [`formatToCNPJAlphanumeric`](#formatToCNPJAlphanumeric). ```js formatToCNPJ("128781"); //=> '12.878.1' formatToCNPJ("32284981000138"); //=> '32.284.981/0001-38' formatToCNPJ("00.0.000.00.00--00-00"); //=> '00.000.000/0000-00' ``` #### `formatToCNPJAlphanumeric` Formats a text containing alphanumeric characters to alphanumeric CNPJ. Supports both numeric and alphanumeric CNPJs in the format `AA.AAA.AAA/AAAA-99`. > Starting in 2026, CNPJs may contain letters in the first 12 characters. ```js formatToCNPJAlphanumeric("AB12CD34EF5602"); //=> 'AB.12C.D34/EF56-02' formatToCNPJAlphanumeric("ab12cd34ef5602"); //=> 'AB.12C.D34/EF56-02' (automatically converts to uppercase) formatToCNPJAlphanumeric("AB.12C.D34/EF56-02"); //=> 'AB.12C.D34/EF56-02' formatToCNPJAlphanumeric("32284981000138"); //=> '32.284.981/0001-38' (also works with numeric CNPJs) ``` #### `formatToCPF` Formats a text containing numbers to CPF. ```js formatToCPF("00000000"); //=> '000.000.00' formatToCPF("00000000000"); //=> '000.000.000-00' formatToCPF("366.418.768-70"); //=> '366.418.768-70' ``` #### `formatToCPFOrCNPJ` Formats a `string` value to CPF or CNPJ depending on its content. Automatically detects if it's a CPF, numeric CNPJ, or alphanumeric CNPJ. ```js formatToCPFOrCNPJ("00000000"); //=> '000.000.00' formatToCPFOrCNPJ("366.418.768-70"); //=> '366.418.768-70' (CPF) formatToCPFOrCNPJ("32284981000138"); //=> '32.284.981/0001-38' (numeric CNPJ) formatToCPFOrCNPJ("AB12CD34EF5602"); //=> 'AB.12C.D34/EF56-02' (alphanumeric CNPJ) formatToCPFOrCNPJ("00.0.000.00.00--00-00"); //=> '00.000.000/0000-00' ``` #### `formatToDate` Formats a `Date` instance to brazilian formatted date, **`DD/MM/YYYY`**. ```js formatToDate(new Date(2002, 7, 21)); //=> '21/08/2002' formatToDate(new Date()); //=> '08/09/2018' ``` #### `formatToDateTime` Formats a `Date` instance to brazilian formatted date and time, **`DD/MM/YYYY HH:mm`**. ```js formatToDateTime(new Date(2002, 7, 21, 18, 30)); //=> '21/08/2002 18:30' ``` #### `formatToList` Formats an `Array` of `string` values into brazilian formatted list. ```js formatToList(["Vitor", "William", "Fernando"]); //=> 'Vitor, William e Fernando' formatToList([]); // => '' formatToList(["1", "2"]); // => '1 e 2' formatToList(["Direito Civil"]); //=> 'Direito Civil' ``` #### `formatToNumber` Formats a number to brazilian formatted number. ```js formatToNumber(0); //=> '0' formatToNumber(-1299); //=> '-1.299' formatToNumber(0.981); //=> '0,981' formatToNumber("19898.1298"); //=> '19.898,1298' ``` #### `formatToPhone` Formats a text containing numbers to common brazilian phone. ```js formatToPhone("11"); //=> '(11' formatToPhone("11971626"); //=> '(11) 9716-26' formatToPhone("11971626799"); //=> '(11) 9 7162-6799' ``` #### `formatToRG` Formats a text containing numbers to RG, specifying the state. > Today, `brazilian-values` supports only **SP** and **RJ** formats. > Other values are just escaped to input. ```js formatToRG("00000000A", "SP"); //=> '00.000.000-A' formatToRG("00.00.0000-0", "RJ"); //=> '00.000.000-0' formatToRG("MG-14.808.688", "MG"); //=> 'MG-14.808.688' ``` #### `formatToHiddenDigits` Formats a `string` with digits by replacing digits within the range by the hider character. ```js formatToHiddenDigits("00.000-000"); //=> '**.*00-000' formatToHiddenDigits("03/04/2002", { hider: "-" }); //=> '--/-4/2002' formatToHiddenDigits("111.111.111-11", { range: [4, 9] }); //=> '111.***.***-11' formatToHiddenDigits("12.345.678-9", { hider: "#", range: 5 }); //=> '##.###.678-9' formatToHiddenDigits("52.715.348/0001-69", { hider: "@", range: -9 }); //=> '52.715.@@@/@@@@-@@' ``` ### Parsers #### `parseToArray` Parses a brazilian formatted list into an Array. ```js parseToArray(""); //=> [] parseToArray("1"); //=> ['1'] parseToArray("1 e 2"); //=> ['1', '2'] parseToArray("Fernanda, Luana e Ana Carolina"); //=> ['Fernanda', 'Luana', 'Ana Carolina'] ``` #### `parseToDate` Parses a brazilian formatted date to a Date instance. > Throws an error if value does not match brazilian date format and if value is an invalid date. ```js parseToDate("28/03/1996"); //=> Date('1996-03-28T03:00:00.000Z') parseToDate("28/03/1996 20:00"); //=> Date('1996-03-28T23:00:00.000Z') parseToDate("28/03/1996 20:00:00"); //=> Date('1996-03-28T23:00:00.000Z') parseToDate("31/02/2018"); //=> throws Error('Value "31/02/2018" is an invalid date.') ``` #### `parseToNumber` Parses a brazilian formatted number to a number. ```js parseToNumber("10"); //=> 10 parseToNumber("-1.299"); //=> -1299 parseToNumber("0,981"); //=> 0.981 parseToNumber("19.898,1298"); //=> 19898.1298 ``` ### Validators #### `isCAEPF` Validates if value is a CAEPF. ```js isCAEPF("45723174000122"); //=> true isCAEPF("457.231.740/001-22"); //=> false isCAEPF("45.723.174/0001-22"); //=> false isCAEPF("411407182"); //=> false isCAEPF("111.111.111/111-11"); //=> false ``` #### `isCEP` Validates if value is a CEP. ```js isCEP("50.833-000"); //=> true isCEP("02998-050"); //=> true isCEP("00000000"); //=> true isCEP("0"); //=> false isCEP("1982891928981982198"); //=> false ``` #### `isCNPJ` Validates if value is a valid CNPJ (numeric or alphanumeric). Accepts both traditional numeric CNPJs and new alphanumeric CNPJs (valid from 2026). > Related: [`isCPFOrCNPJ`](#isCPFOrCNPJ), [`isCNPJAlphanumeric`](#isCNPJAlphanumeric). ```js isCNPJ("41142260000189"); //=> true (numeric CNPJ) isCNPJ("45.723.174/0001-10"); //=> true (formatted numeric CNPJ) isCNPJ("AB12CD34EF5602"); //=> true (alphanumeric CNPJ) isCNPJ("AB.12C.D34/EF56-02"); //=> true (formatted alphanumeric CNPJ) isCNPJ("411407182"); //=> false isCNPJ("11.111.111/1111-11"); //=> false ``` #### `isCNPJAlphanumeric` Validates if value is a valid alphanumeric CNPJ. ```js isCNPJAlphanumeric("AB12CD34EF5602"); //=> true isCNPJAlphanumeric("AB.12C.D34/EF56-02"); //=> true isCNPJAlphanumeric("AB12CD34EF5600"); //=> false ``` #### `isCPF` Validates if value is a CPF. > Related: [`isCPFOrCNPJ`](#isCPFOrCNPJ). ```js isCPF("366.418.768-70"); //=> true isCPF("36641876870"); //=> true isCPF("213.198.013-20"); //=> false isCPF("2131201872781"); //=> false isCPF("11111111111"); //=> false ``` #### `isCPFOrCNPJ` Validates if value is either a valid CPF or CNPJ (numeric or alphanumeric). > Related: [`isCPF`](#isCPF), [`isCNPJ`](#isCNPJ), [`isCNPJAlphanumeric`](#isCNPJAlphanumeric). ```js isCPFOrCNPJ("366.418.768-70"); //=> true (CPF) isCPFOrCNPJ("36641876870"); //=> true (CPF) isCPFOrCNPJ("213.198.013-20"); //=> false isCPFOrCNPJ("2131201872781"); //=> false isCPFOrCNPJ("11111111111"); //=> false isCPFOrCNPJ("41142260000189"); //=> true (numeric CNPJ) isCPFOrCNPJ("45.723.174/0001-10"); //=> true (numeric CNPJ) isCPFOrCNPJ("AB12CD34EF5602"); //=> true (alphanumeric CNPJ) isCPFOrCNPJ("AB.12C.D34/EF56-02"); //=> true (alphanumeric CNPJ) isCPFOrCNPJ("411407182"); //=> false isCPFOrCNPJ("11.111.111/1111-11"); //=> false ``` isCPFOrCNPJ("45.723.174/0001-10"); //=> true isCPFOrCNPJ("411407182"); //=> false isCPFOrCNPJ("11.111.111/1111-11"); //=> false ```` #### `isDate` Validates if value matches brazilian date format and is a valid date. ```js isDate("03/08/2017"); //=> true isDate("28/13/2017"); //=> false isDate("03-08-2017"); //=> false isDate("31/03/18"); //=> false ```` #### `isDDD` Validates if value is a brazilian valid DDD (direct dialing at a distance) code. > Based on [resolution No. 263 of June 8, 2001](https://www.anatel.gov.br/legislacao/resolucoes/16-2001/383-resolucao-263). ```js isDDD("81"); //=> true isDDD("10"); //=> false isDDD("555"); //=> false ``` #### `isPhone` Validates if value matches common brazilian phone number, optionally with DDI, DDD and the ninth digit. If DDD is defined it'll be validated with `isDDD`. ```js isPhone("+55 (11) 9 8273-1182"); //=> true isPhone("11 9 8273 1182"); //=> true isPhone("1139723768"); //=> true isPhone("(23) 3972-3768"); //=> false isPhone("(13) 6 5093-2093"); //=> false isPhone("(81) 555 178"); //=> false ``` ## License Released under [MIT license](./LICENSE). [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2FVitorLuizC%2Fbrazilian-values.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2FVitorLuizC%2Fbrazilian-values?ref=badge_large)