A package for validating postal codes from various countries.
npm install postal-code-checkerpostal-code-checker is a comprehensive JavaScript/TypeScript package for validating postal codes across multiple countries. It provides an easy-to-use API for country selection and postal code validation, making it ideal for forms and address validation in web applications.
- ð Supports postal code validation for over 200 countries
- ð Provides country selection functionality
- ð Includes example postal codes for supported countries
- ð TypeScript support with type definitions
- ðŠķ Lightweight and easy to integrate
``bash`
npm install postal-code-checker
ð Code
`javascript
// Import according to your requirement, we support both ES6 and CommonJS
import { usePostalCodeValidation, getCountryByCode, getAllCountries, Country, CountryCode } from "postal-code-checker";
// OR
const {
usePostalCodeValidation,
getCountryByCode,
getAllCountries,
Country,
CountryCode,
} = require("postal-code-checker");
const { validatePostalCode } = usePostalCodeValidation();
// Validate a postal code
const isValid = validatePostalCode("US", "12345"); // Returns true
// Get country information
const country = getCountryByCode("US");
console.log(country.countryName); // "United States of America"
// Get all available countries
const countries = getAllCountries();
`
ð Expand Code
`javascript
const { usePostalCodeValidation } = require("postal-code-checker");
const { validatePostalCode } = usePostalCodeValidation();
// Validate a postal code
const isValid = validatePostalCode("US", "12345"); // Returns true
// Get country information
const country = getCountryByCode("US");
console.log(country.countryName); // "United States of America"
// Get all available countries
const countries = getAllCountries();
`
ð Expand Code
`typescript
import { ChangeEvent, FC, useState } from "react";
import { usePostalCodeValidation, getCountryByCode, getAllCountries, Country, CountryCode } from "postal-code-checker";
const PostalCodeValidator: FC = () => {
const { validatePostalCode } = usePostalCodeValidation();
const [selectedCountry, setSelectedCountry] = useState
const [postalCode, setPostalCode] = useState
const [isValid, setIsValid] = useState
const handleCountryChange = (e: ChangeEvent
const country = getCountryByCode(e.target.value as CountryCode);
setSelectedCountry(country);
setIsValid(null);
setPostalCode("");
};
const handlePostalCodeChange = (e: ChangeEvent
const code = e.target.value;
setPostalCode(code);
if (selectedCountry) {
setIsValid(validatePostalCode(selectedCountry.countryCode, code));
}
};
return (
{isValid ? "Valid postal code" : "Invalid postal code"}
}export default PostalCodeValidator;
`
ð Expand Code
`javascript
import { useState } from "react";
import { usePostalCodeValidation, getCountryByCode, getAllCountries } from "postal-code-checker";
const PostalCodeValidator = () => {
const { validatePostalCode } = usePostalCodeValidation();
const [selectedCountry, setSelectedCountry] = useState(null);
const [postalCode, setPostalCode] = useState("");
const [isValid, setIsValid] = useState(null);
const handleCountryChange = (e) => {
const country = getCountryByCode(e.target.value);
setSelectedCountry(country);
setIsValid(null);
setPostalCode("");
};
const handlePostalCodeChange = (e) => {
const code = e.target.value;
setPostalCode(code);
if (selectedCountry) {
setIsValid(validatePostalCode(selectedCountry.countryCode, code));
}
};
return (
{isValid ? "Valid postal code" : "Invalid postal code"}
}export default PostalCodeValidator;
`
Apart from the usage examples shown above, this package can be seamlessly integrated with any JavaScript framework or library, including but not limited to Angular, Vue.js, Next.js, and many more. The flexible design of postal-code-checker ensures it can be easily incorporated into your project, regardless of your chosen tech stack.
Returns an object with the following methods:
- validatePostalCode(countryCode: CountryCode, postalCode: string): boolean
Returns an object with the following methods:
- getCountryByCode(countryCode: CountryCode): Country | null
-
`typescript
type CountryCode = string; // ISO 3166-1 alpha-2 country code
type Country = {
postalCodeRegex: string;
examplePostalCodes: string[];
isGenericRegex: boolean;
countryName: string;
countryCode: CountryCode;
};
`
- [ ] Use regex pattern information to generate examples and drop hard coded examples from resource to reduce package size
- [ ] Move to pure css styles at dev sandbox (live dev playground) & drop antd library usage to reduce package size
- [ ] Implement more specific regex patterns for countries currently using generic patterns
- [ ] Add support for state/province validation for countries
- [ ] Create a demo website with interactive examples
- [ ] Add support for custom regex patterns and country data
- [ ] Optimize package size and performance
- [ ] Add internationalization support for country names
- [ ] Implement reverse lookup functionality (postal code to country/region)
- [ ] Add postal code validation with additional context (city, region)
- [ ] Implement partial matching and suggestion functionality
- [ ] Add historical postal code validation
- [ ] Add batch validation for multiple postal codes
- [ ] Allow custom error messages for different validation scenarios
- [ ] Implement postal code type identification (residential, commercial, etc.)
- [ ] Accept custom resource as config and override/merge inbuilt resource
- [ ] Add unit tests for all utility functions
Pull requests are welcome.
When contributing, please follow these guidelines:
1. Always start by checking out from the master branch:
ð Show More
`
git checkout master
git pull
git checkout -b your-branch-name
2. Use meaningful names for your branches. Follow these patterns:
ð Show Examples
- For bug fixes:
`
bugfix/short-description-of-the-fix
Example: bugfix/fix-null-return-australia-code
- For new features or improvements:
`
feature/short-description-of-feature
Example: feature/add-getAllCountries-unit-test
3. Please make sure to update tests as appropriate.
4. Ensure your code follows the project's coding standards and conventions.
5. Write clear, concise commit messages describing your changes.
6. Update or add unit tests to cover your changes.
We appreciate your contributions to making postal-code-checker` better!
Postal code data used in this project is sourced from the European Central Bank (ECB).
Note : This data has been processed and reformatted for use in this project.
- Source: [\[ECB\]](https://www.ecb.europa.eu/)
- Retrieved on: 4th AUG 2024