Test all ValidBR features directly in your browser: 🚀 Open Interactive Demo
💡 Tip: Open the
demo.htmlfile in your browser to test all ValidBR features interactively!
ValidBR is a comprehensive Brazilian validation library available for Node.js, Python, and PHP. It provides robust validation for Brazilian documents, phone numbers, addresses, and personal information with advanced features like mask application, state identification, and data sanitization.
npm install validbr
pip install validbr
composer require validbr/validbr
const ValidBR = require('validbr');
// CPF validation
console.log(ValidBR.cpf.isValid('123.456.789-09')); // true
console.log(ValidBR.cpf.generate()); // Generate valid CPF
console.log(ValidBR.cpf.getState('12345678909')); // 'São Paulo'
// CNH validation
console.log(ValidBR.cnh.isValid('02650306461')); // true
console.log(ValidBR.cnh.generate()); // Generate valid CNH
// Voter ID validation
console.log(ValidBR.tituloEleitor.isValid('123456789012')); // true
console.log(ValidBR.tituloEleitor.generate()); // Generate valid Voter ID
// PIS validation
console.log(ValidBR.pis.isValid('123.45678.90-1')); // true
console.log(ValidBR.pis.generate()); // Generate valid PIS
// Phone validation
console.log(ValidBR.phone.isValid('(11) 91234-5678')); // true
console.log(ValidBR.phone.getState('11')); // 'São Paulo'
// Apply mask
console.log(ValidBR.cpf.applyMask('12345678909')); // '123.456.789-09'
console.log(ValidBR.phone.applyMask('11912345678')); // '(11) 91234-5678'
from validbr import validbr
# CPF validation
print(validbr.cpf.is_valid('123.456.789-09')) # True
print(validbr.cpf.generate()) # Generate valid CPF
print(validbr.cpf.get_state('12345678909')); // 'São Paulo'
# CNH validation
print(validbr.cnh.is_valid('02650306461')) # True
print(validbr.cnh.generate()) # Generate valid CNH
# Voter ID validation
print(validbr.titulo_eleitor.is_valid('123456789012')) # True
print(validbr.titulo_eleitor.generate()) # Generate valid Voter ID
# PIS validation
print(validbr.pis.is_valid('123.45678.90-1')) # True
print(validbr.pis.generate()) # Generate valid PIS
# Phone validation
print(validbr.phone.is_valid('(11) 91234-5678')); # True
print(validbr.phone.get_state('11')); # 'São Paulo'
# Apply mask
print(validbr.cpf.apply_mask('12345678909')); # '123.456.789-09'
print(validbr.phone.apply_mask('11912345678')); # '(11) 91234-5678'
use ValidBR\ValidBR;
// CPF validation
echo ValidBR::cpf()->isValid('123.456.789-09') ? 'true' : 'false'; // true
echo ValidBR::cpf()->generate(); // Generate valid CPF
echo ValidBR::cpf()->getState('12345678909'); // 'São Paulo'
// CNH validation
echo ValidBR::cnh()->isValid('02650306461') ? 'true' : 'false'; // true
echo ValidBR::cnh()->generate(); // Generate valid CNH
// Voter ID validation
echo ValidBR::tituloEleitor()->isValid('123456789012') ? 'true' : 'false'; // true
echo ValidBR::tituloEleitor()->generate(); // Generate valid Voter ID
// PIS validation
echo ValidBR::pis()->isValid('123.45678.90-1') ? 'true' : 'false'; // true
echo ValidBR::pis()->generate(); // Generate valid PIS
// Phone validation
echo ValidBR::phone()->isValid('(11) 91234-5678') ? 'true' : 'false'; // true
echo ValidBR::phone()->getState('11'); // 'São Paulo'
// Apply mask
echo ValidBR::cpf()->applyMask('12345678909'); // '123.456.789-09'
echo ValidBR::phone()->applyMask('11912345678'); // '(11) 91234-5678'
// Node.js
ValidBR.cpf.isValid('123.456.789-09'); // true/false
ValidBR.cpf.generate(); // Generate valid CPF
ValidBR.cpf.applyMask('12345678909'); // '123.456.789-09'
ValidBR.cpf.removeMask('123.456.789-09'); // '12345678909'
ValidBR.cpf.getState('12345678909'); // 'São Paulo'
// Node.js
ValidBR.cnpj.isValid('12.345.678/0001-95'); // true/false
ValidBR.cnpj.generate(); // Generate valid CNPJ
ValidBR.cnpj.applyMask('12345678000195'); // '12.345.678/0001-95'
ValidBR.cnpj.removeMask('12.345.678/0001-95'); // '12345678000195'
ValidBR.cnpj.getState('12345678000195'); // 'São Paulo'
// Node.js
ValidBR.phone.isValid('(11) 91234-5678'); // true/false
ValidBR.phone.getDDD('(11) 91234-5678'); // '11'
ValidBR.phone.getState('11'); // 'São Paulo'
ValidBR.phone.applyMask('11912345678'); // '(11) 91234-5678'
ValidBR.phone.removeMask('(11) 91234-5678'); // '11912345678'
ValidBR.phone.getValidDDDs(); // Array of valid DDDs
// Node.js
ValidBR.email.isValid('user@example.com'); // true/false
ValidBR.email.sanitize(' user@example.com '); // 'user@example.com'
ValidBR.email.getDomain('user@example.com'); // 'example.com'
ValidBR.email.getUsername('user@example.com'); // 'user'
ValidBR.email.isBrazilianProvider('user@uol.com.br'); // true
// Node.js
ValidBR.fullName.isValid('João Silva Santos'); // true/false
ValidBR.fullName.sanitize('João Silva Santos '); // 'João Silva Santos'
ValidBR.fullName.getFirstName('João Silva Santos'); // 'João'
ValidBR.fullName.getLastName('João Silva Santos'); // 'Santos'
ValidBR.fullName.getInitials('João Silva Santos'); // 'JSS'
ValidBR.fullName.hasCommonBrazilianName('João'); // true
// Node.js
ValidBR.birthDate.isValid('1990-05-15'); // true/false
ValidBR.birthDate.getAge('1990-05-15'); // Current age
ValidBR.birthDate.isAdult('1990-05-15'); // true/false
ValidBR.birthDate.isElderly('1940-05-15'); // true/false
ValidBR.birthDate.isMinor('2010-05-15'); // true/false
ValidBR.birthDate.format('1990-05-15', 'DD/MM/YYYY'); // '15/05/1990'
ValidBR.birthDate.getZodiacSign('1990-05-15'); // 'Touro'
// Node.js
ValidBR.cep.isValid('01234-567'); // true/false
ValidBR.cep.getInfo('01234-567'); // Get address info (async)
ValidBR.cep.applyMask('01234567'); // '01234-567'
ValidBR.cep.removeMask('01234-567'); // '01234567'
ValidBR.cep.getState('01234567'); // 'São Paulo'
ValidBR.cep.isFromSaoPaulo('01234567'); // true/false
ValidBR.cep.getRegion('01234567'); // 'Sudeste'
// Node.js
ValidBR.rg.isValid('12.345.678-9', 'SP'); // true/false (state required)
ValidBR.rg.applyMask('123456789'); // '12.345.678-9'
ValidBR.rg.removeMask('12.345.678-9'); // '123456789'
ValidBR.rg.generate('SP'); // Generate valid RG for SP
ValidBR.rg.getValidStates(); // Array of supported states
// Node.js
ValidBR.ie.isValid('123.456.789', 'SP'); // true/false
ValidBR.ie.applyMask('123.456.789', 'SP'); // '123.456.789'
ValidBR.ie.removeMask('123.456.789'); // '123456789'
ValidBR.ie.generate('SP'); // Generate valid IE for SP
ValidBR.ie.getValidStates(); // Array of supported states
// Node.js
ValidBR.cnh.isValid('02650306461'); // true/false
ValidBR.cnh.generate(); // Generate valid CNH
ValidBR.cnh.applyMask('02650306461'); // '02650306461'
ValidBR.cnh.removeMask('02650306461'); // '02650306461'
// Node.js
ValidBR.tituloEleitor.isValid('123456789012'); // true/false
ValidBR.tituloEleitor.generate(); // Generate valid Voter ID
ValidBR.tituloEleitor.applyMask('123456789012'); // '1234 5678 9012'
ValidBR.tituloEleitor.removeMask('1234 5678 9012'); // '123456789012'
// Node.js
ValidBR.pis.isValid('123.45678.90-1'); // true/false
ValidBR.pis.generate(); // Generate valid PIS
ValidBR.pis.applyMask('12345678901'); // '123.45678.90-1'
ValidBR.pis.removeMask('123.45678.90-1'); // '12345678901'
// Node.js
ValidBR.sanitize(' test@example.com '); // 'test@example.com'
ValidBR.removeNonNumeric('abc123def456'); // '123456'
ValidBR.removeNonAlphabetic('João123Silva'); // 'JoãoSilva'
# Navigate to docker directory
cd docker
# Run all tests
docker-compose up --build
# Run tests for specific language
docker-compose run nodejs npm test
docker-compose run python python -m pytest
docker-compose run php composer test
# Node.js
cd nodejs
npm install
npm test
# Python
cd python
pip install -e .
python -m pytest
# PHP
cd php
composer install
composer test
# Node.js
npm run test:coverage
# Python
python -m pytest --cov=validbr
# PHP
composer test:coverage
Open demo.html in your browser to test all ValidBR features interactively. The demo includes:
We welcome contributions! Please read our Contributing Guide for details on:
docker-compose up --buildThis project is licensed under the MIT License - see the LICENSE file for details.
See CHANGELOG.md for version history and changes.
For information on how to publish ValidBR to package repositories, see the Publishing Guide.
# Run all tests
./publish.sh test
# Publish to NPM
./publish.sh npm
# Publish to PyPI
./publish.sh pypi
# Check Packagist configuration
./publish.sh packagist
# Complete process (tests + publishing)
./publish.sh all
# NPM
cd nodejs && npm publish
# PyPI
cd python && python setup.py sdist bdist_wheel && twine upload dist/*
# Packagist
# Connect Git repository to Packagist.org
ValidBR é uma biblioteca abrangente de validação brasileira disponível para Node.js, Python e PHP. Ela fornece validação robusta para documentos brasileiros, números de telefone, endereços e informações pessoais com recursos avançados como aplicação de máscaras, identificação de estado e sanitização de dados.
npm install validbr
pip install validbr
composer require validbr/validbr
const ValidBR = require('validbr');
// Validação de CPF
console.log(ValidBR.cpf.isValid('123.456.789-09')); // true
console.log(ValidBR.cpf.generate()); // Gerar CPF válido
console.log(ValidBR.cpf.getState('12345678909')); // 'São Paulo'
// Validação de telefone
console.log(ValidBR.phone.isValid('(11) 91234-5678')); // true
console.log(ValidBR.phone.getState('11')); // 'São Paulo'
// Aplicar máscara
console.log(ValidBR.cpf.applyMask('12345678909')); // '123.456.789-09'
console.log(ValidBR.phone.applyMask('11912345678')); // '(11) 91234-5678'
from validbr import ValidBR
# Validação de CPF
print(ValidBR.cpf.is_valid('123.456.789-09')) # True
print(ValidBR.cpf.generate()) # Gerar CPF válido
print(ValidBR.cpf.get_state('12345678909')); // 'São Paulo'
# Validação de telefone
print(ValidBR.phone.is_valid('(11) 91234-5678')); // true
print(ValidBR.phone.get_state('11')); // 'São Paulo'
# Aplicar máscara
print(ValidBR.cpf.apply_mask('12345678909')); // '123.456.789-09'
print(ValidBR.phone.apply_mask('11912345678')); // '(11) 91234-5678'
use ValidBR\ValidBR;
// Validação de CPF
echo ValidBR::cpf()->isValid('123.456.789-09') ? 'true' : 'false'; // true
echo ValidBR::cpf()->generate(); // Gerar CPF válido
echo ValidBR::cpf()->getState('12345678909'); // 'São Paulo'
// Validação de telefone
echo ValidBR::phone()->isValid('(11) 91234-5678') ? 'true' : 'false'; // true
echo ValidBR::phone()->getState('11'); // 'São Paulo'
# Aplicar máscara
echo ValidBR::cpf()->applyMask('12345678909'); // '123.456.789-09'
echo ValidBR::phone()->applyMask('11912345678'); // '(11) 91234-5678'
Aceitamos contribuições! Por favor, leia nosso Guia de Contribuição para detalhes sobre:
docker-compose up --build
FAQs
A comprehensive Brazilian validation library for Python
We found that validbr demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Socket’s new Tier 1 Reachability filters out up to 80% of irrelevant CVEs, so security teams can focus on the vulnerabilities that matter.
Research
/Security News
Ongoing npm supply chain attack spreads to DuckDB: multiple packages compromised with the same wallet-drainer malware.
Security News
The MCP Steering Committee has launched the official MCP Registry in preview, a central hub for discovering and publishing MCP servers.