Tax Document Input Plugin

A vanilla JavaScript plugin for automatic formatting of tax documents from different countries, similar to intl-tel-input but for documents like CPF, CNPJ, NIF, NIPC, SSN, EIN, etc.

🚀 Features

Vanilla JavaScript: No external dependencies
Automatic Formatting: Applies masks as you type
Smart Detection: Automatically identifies document type based on length
Complete Validation: Real validation algorithms (check digits, etc.)
Multi-country: Initial support for Brazil, Portugal and United States
Country Selector: Interface similar to intl-tel-input with flags
Visible Flag: Displays the selected country flag next to the input
GeoIP Lookup: Automatic country detection via IP (optional)
Complete API: Public methods for programmatic control
Custom Events: Event listeners for country changes
Configurable: Options to customize behavior and appearance
Modular Validation System: Rules organized by country in separate files

📋 Supported Documents

Brazil 🇧🇷

CPF (11 digits): 123.456.789-01
CNPJ (14 digits): 12.345.678/0001-90

Portugal 🇵🇹

NIF (9 digits): 123 456 789
NIPC (9 digits): 123 456 789

United States 🇺🇸

SSN (9 digits): 123-45-6789
EIN (9 digits): 12-3456789

🛠️ Installation

Via CDN

<script src="https://cdn.jsdelivr.net/npm/tax-document-input@latest/dist/tax-document-input.min.js"></script>

Via NPM

npm install tax-document-input

Direct Download

Download the tax-document-input.js file and include in your project:

<script src="path/to/tax-document-input.js"></script>

📖 Basic Usage

HTML

<input type="text" id="tax-document" />

JavaScript

// Basic initialization
const taxInput = new TaxDocumentInput(document.getElementById('tax-document'));

// With options
const taxInput = new TaxDocumentInput(document.getElementById('tax-document'), {
    placeholder: 'Enter your document',
    defaultCountry: 'br',
    autoGeolocate: false,
    onlyCountries: ['br', 'pt']
});

⚙️ Configuration Options

Option	Type	Default	Description
`placeholder`	string	`'Document Tax'`	Input placeholder text
`defaultCountry`	string	`'br'`	Default country (ISO2 code)
`autoGeolocate`	boolean	`false`	Enable automatic country detection via IP
`onlyCountries`	array	`[]`	Limit available countries (e.g. `['br', 'pt']`)
`geoIpLookup`	function	`null`	Custom function for IP country lookup

Example with all options:

const taxInput = new TaxDocumentInput(document.getElementById('tax-document'), {
    placeholder: 'Taxpayer Number',
    defaultCountry: 'pt',
    autoGeolocate: true,
    onlyCountries: ['br', 'pt', 'us'],
    geoIpLookup: function(callback) {
        // Custom implementation
        fetch('https://your-geoip-api.com/lookup')
            .then(res => res.json())
            .then(data => callback(data.country))
            .catch(() => callback('br')); // fallback
    }
});

🌍 GeoIP Lookup

Automatic Lookup

// Uses ipapi.co API by default
const taxInput = new TaxDocumentInput(document.getElementById('input'), {
    autoGeolocate: true
});

Custom Lookup

// Similar to intl-tel-input
const taxInput = new TaxDocumentInput(document.getElementById('input'), {
    autoGeolocate: true,
    geoIpLookup: callback => {
        fetch("https://ipapi.co/json")
            .then(res => res.json())
            .then(data => callback(data.country_code))
            .catch(() => callback("br"));
    }
});

🎯 Public API

Methods

`getSelectedCountry()`

Returns the selected country ISO2 code.

const country = taxInput.getSelectedCountry(); // 'br'

`getSelectedCountryData()`

Returns complete data of the selected country.

const countryData = taxInput.getSelectedCountryData();
// { name: 'Brasil', iso2: 'br', flag: '🇧🇷', documents: {...} }

`getCurrentDocumentType()`

Returns the current document type based on typed length.

const docType = taxInput.getCurrentDocumentType(); // 'cpf' or 'cnpj'

`setCountry(countryCode)`

Sets the country programmatically.

taxInput.setCountry('pt'); // Set Portugal

`getValue()`

Returns the formatted input value.

const value = taxInput.getValue(); // '123.456.789-01'

`getCleanValue()`

Returns only numbers, without formatting.

const cleanValue = taxInput.getCleanValue(); // '12345678901'

`isValid()`

Checks if the document is complete and valid.

const isValid = taxInput.isValid(); // true/false

`validateDocument()`

Returns complete document validation with details.

const validation = taxInput.validateDocument();
// {
//   isValid: true,
//   error: null,
//   documentType: 'cpf',
//   documentCategory: 'personal',
//   country: 'br',
//   details: { formatted: '123.456.789-01', type: 'personal' }
// }

`getCurrentDocumentInfo()`

Returns complete information about the current document type.

const info = taxInput.getCurrentDocumentInfo();
// {
//   type: 'cpf',
//   category: 'personal',
//   length: 11,
//   mask: 'XXX.XXX.XXX-XX',
//   country: 'br'
// }

🎪 Events

`countrychange`

Fired when the country is changed.

document.getElementById('tax-document').addEventListener('countrychange', function(e) {
    console.log('Previous country:', e.detail.previousCountry);
    console.log('New country:', e.detail.newCountry);
    console.log('Country data:', e.detail.countryData);
});

Practical example:

const input = document.getElementById('tax-document');
const taxInput = new TaxDocumentInput(input);

// Listener for country change
input.addEventListener('countrychange', function(e) {
    console.log(`Country changed from ${e.detail.previousCountry} to ${e.detail.newCountry}`);
    
    // Clear previous validations, change labels, etc.
    updateFormLabels(e.detail.newCountry);
});

// Listener for input changes
input.addEventListener('input', function(e) {
    const docType = taxInput.getCurrentDocumentType();
    const isValid = taxInput.isValid();
    
    console.log(`Document: ${docType}, Valid: ${isValid}`);
});

🎨 CSS Customization

The plugin adds CSS classes that can be customized:

/* Main container */
.tax-document-input {
    border: 2px solid #007bff;
    border-radius: 8px;
}

/* Country button */
.tax-document-input__country-button {
    background-color: #f8f9fa;
}

/* Input field */
.tax-document-input__field {
    font-size: 16px;
    padding: 12px;
}

/* Countries dropdown */
.tax-document-input__dropdown {
    border: 2px solid #007bff;
    box-shadow: 0 4px 8px rgba(0,0,0,0.2);
}

/* Dropdown item */
.tax-document-input__dropdown-item:hover {
    background-color: #007bff;
    color: white;
}

🔧 Advanced Usage

Multiple instances

// Initialize multiple inputs at once
const instances = TaxDocumentInput.init('.tax-document-input', {
    defaultCountry: 'br'
});

// Or individually
const personalDoc = new TaxDocumentInput(document.getElementById('personal-doc'), {
    onlyCountries: ['br'],
    placeholder: 'CPF'
});

const companyDoc = new TaxDocumentInput(document.getElementById('company-doc'), {
    onlyCountries: ['br'],
    placeholder: 'CNPJ'
});

Form validation

const form = document.getElementById('registration-form');
const taxInput = new TaxDocumentInput(document.getElementById('tax-document'));

form.addEventListener('submit', function(e) {
    if (!taxInput.isValid()) {
        e.preventDefault();
        alert('Invalid tax document!');
        return;
    }
    
    // Send data
    const formData = {
        document: taxInput.getCleanValue(),
        documentType: taxInput.getCurrentDocumentType(),
        country: taxInput.getSelectedCountry()
    };
    
    console.log('Data to send:', formData);
});

Framework integration

// Vue.js
new Vue({
    mounted() {
        this.taxInput = new TaxDocumentInput(this.$refs.taxDocument, {
            defaultCountry: 'br'
        });
        
        this.$refs.taxDocument.addEventListener('countrychange', (e) => {
            this.selectedCountry = e.detail.newCountry;
        });
    },
    
    beforeDestroy() {
        if (this.taxInput) {
            this.taxInput.destroy();
        }
    }
});

// React (in useEffect)
useEffect(() => {
    const taxInput = new TaxDocumentInput(inputRef.current);
    
    return () => {
        taxInput.destroy();
    };
}, []);

🌍 Expanding to Other Countries

Soon, the plugin will support more countries. To contribute, create a pull request.

🐛 Troubleshooting

Input is not being formatted

Check if the plugin was initialized correctly
Make sure the element exists in the DOM
Check the console for JavaScript errors

Dropdown doesn't appear

Check for CSS conflicts with z-index
Make sure the parent container doesn't have overflow: hidden

GeoIP Lookup doesn't work

HTTPS is recommended for external APIs
Check if the ipapi.co API is accessible
Configure a fallback in your custom geoIpLookup
Set autoGeolocate: false if not needed

📄 License

MIT License - see the LICENSE file for details.

🤝 Contributing

Fork the project
Create a feature branch (git checkout -b feature/new-feature)
Commit your changes (git commit -am 'Add new feature')
Push to the branch (git push origin feature/new-feature)
Open a Pull Request

📞 Support

🐛 Issues: GitHub Issues
📖 Documentation: GitHub Wiki

☕ Sponsors

If you find this plugin useful, consider sponsoring its development:

Sponsor on GitHub

📝 Changelog

v1.0.0

Initial release
Support for Brazil, Portugal and United States
Automatic formatting for CPF, CNPJ, NIF, NIPC, SSN, EIN
Interface with country selector
Complete API with public methods
Custom events
Optional geolocation

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
dist		dist
src		src
.gitignore		.gitignore
.npmignore		.npmignore
README.md		README.md
package.json		package.json
publish.sh		publish.sh
rollup.config.js		rollup.config.js

phpiando/tax-document-input

Folders and files

Latest commit

History

Repository files navigation