Formatter Locale

A utility library for formatting Brazilian document values and phone numbers.

🚀 NEW in v1.3.0: Full support for the 2026 alphanumeric CNPJ format!

This library now supports the new alphanumeric CNPJ format established by the Brazilian Federal Revenue Service (Receita Federal) for 2026, maintaining full compatibility with traditional numeric CNPJs.

Installation

npm install formatter-locale

Usage

import { phoneFormatter, ssnFormatter, einFormatter } from 'formatter-locale';

// Phone formatting
const phone = phoneFormatter('pt-BR')('11999887766');
console.log(phone); // (11) 99988-7766

// CPF formatting
const cpf = ssnFormatter('pt-BR')('12345678901');
console.log(cpf); // 123.456.789-01

// CNPJ formatting - Traditional numeric format
const numericCNPJ = einFormatter('pt-BR')('12345678000195');
console.log(numericCNPJ); // 12.345.678/0001-95

// 🆕 CNPJ formatting - New 2026 alphanumeric format
const alphanumericCNPJ = einFormatter('pt-BR')('A1B2C3D4E5F612');
console.log(alphanumericCNPJ); // A1.B2C.3D4/E5F6-12

Validation

To check if a value is valid before formatting:

import { einFormatter } from 'formatter-locale';

const formatter = einFormatter('pt-BR');

// Formatting always returns a result, even for invalid values
console.log(formatter('123')); // "123" (too short)
console.log(formatter('12345678000195')); // "12.345.678/0001-95" (valid)
console.log(formatter('A1B2C3D4E5F612')); // "A1.B2C.3D4/E5F6-12" (valid)

// For stricter validation, use dedicated validation libraries
// This library focuses on visual formatting

Features

📱 phoneFormatter(locale)

Formats Brazilian phone numbers.

• Support for landline and mobile phones
• Area code formatting
• International number support

📄 ssnFormatter(locale)

Formats CPF numbers.

• Progressive formatting during typing
• Automatic removal of special characters

🏢 einFormatter(locale)

Formats CNPJ numbers with full support for both formats:

• Traditional numeric format: 12.345.678/0001-95
• 🆕 New 2026 alphanumeric format: A1.B2C.3D4/E5F6-12

About the Alphanumeric CNPJ Format

The Brazilian Federal Revenue Service (Receita Federal) is implementing a new alphanumeric CNPJ format starting in 2026 to expand registration capacity. This library provides automatic detection and formatting for both formats:

Format Structure:

• 12 alphanumeric characters (letters A-Z or numbers 0-9) in the base registration
• 2 numeric characters for check digits (DV)
• Same visual pattern: XX.XXX.XXX/XXXX-YY

Key Features:

• Automatic detection: the library identifies if input contains letters and applies the appropriate format
• Case normalization: lowercase letters are automatically converted to uppercase
• Character validation: only alphanumeric characters are accepted (A-Z, 0-9)
• Progressive formatting: works during typing for better UX

Examples:

// Numeric CNPJ (traditional)
einFormatter('pt-BR')('12345678000195')  // → "12.345.678/0001-95"

// Alphanumeric CNPJ (new format)
einFormatter('pt-BR')('A1B2C3D4E5F612')  // → "A1.B2C.3D4/E5F6-12"
einFormatter('pt-BR')('1A2B3C4D567890')  // → "1A.2B3.C4D/5678-90"
einFormatter('pt-BR')('AB345678WXYZ95')  // → "AB.345.678/WXYZ-95"

// Lowercase input (automatically converted)
einFormatter('pt-BR')('a1b2c3d4e5f612')  // → "A1.B2C.3D4/E5F6-12"

// With special characters (automatically removed)
einFormatter('pt-BR')('A1-B2-C3-D4-E5-F6-12')  // → "A1.B2C.3D4/E5F6-12"

CNPJ Validation

The library includes automatic validation that detects:

❌ Common errors:

• CNPJ with less than 14 characters
• CNPJ with invalid characters (special symbols)
• All-zero CNPJ (00.000.000/0000-00)
• Incorrect check digits
• Invalid mixed format (numbers and letters in wrong positions)

✅ Accepted formats:

• Numeric: 12345678000195 or 12.345.678/0001-95
• Alphanumeric: A1B2C3D4E5F612 or A1.B2C.3D4/E5F6-12
• With or without formatting mask

⚙️ Behavior with invalid data:

• Too short data: returns without formatting
• Invalid characters: automatically removed
• Too long data: truncated to 14 characters
• Empty/null input: returns empty string

Compatibility

✅ Full support for the new alphanumeric CNPJ format (2026)
✅ Maintains 100% compatibility with traditional numeric CNPJ format
✅ Automatic detection and formatting for both formats
✅ Progressive formatting during user input
✅ Case-insensitive input with automatic uppercase conversion
✅ Robust special character removal

What's New in v1.3.0

🎉 Alphanumeric CNPJ Support

• New function formatAlphaNumericEIN: Handles the new 2026 CNPJ format with letters and numbers
• Automatic format detection: The library automatically detects if the input contains letters and applies the appropriate formatting
• Backward compatible: All existing numeric CNPJ formatting continues to work without any changes
• Comprehensive test coverage: 17+ test cases covering all scenarios

📋 Technical Details

• First 12 characters can be alphanumeric (A-Z, 0-9)
• Last 2 characters are always numeric (check digits)
• Format pattern: XX.XXX.XXX/XXXX-YY
• Letters are automatically converted to uppercase
• Based on Receita Federal specifications for 2026

Disclaimer and License

⚠️ DISCLAIMER: This library is provided "as is" for formatting purposes only. The authors and contributors are not responsible for:

• Validation accuracy of documents
• Legal compliance of formatted values
• Any damages or losses resulting from the use of this library
• Business decisions made based on the formatted output

📋 IMPORTANT NOTES:

• This is a formatting library, not a validation service
• Always verify document authenticity through official channels
• The 2026 alphanumeric CNPJ format implementation is based on publicly available specifications
• Users are responsible for ensuring compliance with local regulations

🔒 NO WARRANTY: This software is provided without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and non-infringement.

License

MIT License

Copyright (c) 2025-present Emanuel Resende

• License: MIT
• Package: npm

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.