From b70b7e1e4a5f226651155a0f7d168cbb4094fd91 Mon Sep 17 00:00:00 2001 From: Pranav Date: Tue, 25 Aug 2026 03:15:33 +0530 Subject: [PATCH] docs: improve isEmail option documentation --- README.md | 2 +- src/lib/isEmail.js | 47 +++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 47 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e8b7aedd9..456132cac 100644 --- a/README.md +++ b/README.md @@ -106,7 +106,7 @@ Validator | Description **isDecimal(str [, options])** | check if the string represents a decimal number, such as 0.1, .3, 1.1, 1.00003, 4.0, etc.

`options` is an object which defaults to `{force_decimal: false, decimal_digits: '1,', locale: 'en-US'}`.

`locale` determines the decimal separator and is one of `['ar', 'ar-AE', 'ar-BH', 'ar-DZ', 'ar-EG', 'ar-IQ', 'ar-JO', 'ar-KW', 'ar-LB', 'ar-LY', 'ar-MA', 'ar-QA', 'ar-QM', 'ar-SA', 'ar-SD', 'ar-SY', 'ar-TN', 'ar-YE', 'bg-BG', 'cs-CZ', 'da-DK', 'de-DE', 'el-GR', 'en-AU', 'en-GB', 'en-HK', 'en-IN', 'en-NZ', 'en-US', 'en-ZA', 'en-ZM', 'eo', 'es-ES', 'fa', 'fa-AF', 'fa-IR', 'fr-FR', 'fr-CA', 'hu-HU', 'id-ID', 'it-IT', 'ku-IQ', 'nb-NO', 'nl-NL', 'nn-NO', 'pl-PL', 'pl-Pl', 'pt-BR', 'pt-PT', 'ru-RU', 'sl-SI', 'sr-RS', 'sr-RS@latin', 'sv-SE', 'tr-TR', 'uk-UA', 'vi-VN']`.
**Note:** `decimal_digits` is given as a range like '1,3', a specific value like '3' or min like '1,'. **isDivisibleBy(str, number)** | check if the string is a number that is divisible by another. **isEAN(str)** | check if the string is an [EAN (European Article Number)][European Article Number]. -**isEmail(str [, options])** | check if the string is an email.

`options` is an object which defaults to `{ allow_display_name: false, require_display_name: false, allow_utf8_local_part: true, require_tld: true, allow_ip_domain: false, allow_underscores: false, domain_specific_validation: false, blacklisted_chars: '', host_blacklist: [] }`. If `allow_display_name` is set to true, the validator will also match `Display Name `. If `require_display_name` is set to true, the validator will reject strings without the format `Display Name `. If `allow_utf8_local_part` is set to false, the validator will not allow any non-English UTF8 character in email address' local part. If `require_tld` is set to false, email addresses without a TLD in their domain will also be matched. If `ignore_max_length` is set to true, the validator will not check for the standard max length of an email. If `allow_ip_domain` is set to true, the validator will allow IP addresses in the host part. If `domain_specific_validation` is true, some additional validation will be enabled, e.g. disallowing certain syntactically valid email addresses that are rejected by Gmail. If `blacklisted_chars` receives a string, then the validator will reject emails that include any of the characters in the string, in the name part. If `host_blacklist` is set to an array of strings or regexp, and the part of the email after the `@` symbol matches one of the strings defined in it, the validation fails. If `host_whitelist` is set to an array of strings or regexp, and the part of the email after the `@` symbol matches none of the strings defined in it, the validation fails. +**isEmail(str [, options])** | check if the string is an email.

`options` is an object which defaults or falls back to `{ allow_display_name: false, require_display_name: false, allow_utf8_local_part: true, require_tld: true, allow_ip_domain: false, allow_underscores: false, domain_specific_validation: false, blacklisted_chars: '', ignore_max_length: false, host_blacklist: [], host_whitelist: [] }`.

`allow_display_name` - if set to true, the validator will also match `Display Name `.
`require_display_name` - if set to true, the validator will reject strings without the format `Display Name `.
`allow_utf8_local_part` - if set to false, the validator will not allow any non-English UTF-8 character in the email address' local part.
`require_tld` - if set to false, email addresses without a TLD in their domain will also be matched.
`ignore_max_length` - if set to true, the validator will not check the standard max length of an email, the local part, the domain, or domain labels.
`allow_ip_domain` - if set to true, the validator will allow IP addresses in the host part, including bracket-wrapped IP literals.
`allow_underscores` - if set to true, the validator will allow underscores in the domain part.
`domain_specific_validation` - if set to true, the validator will enable additional provider-specific validation, currently including Gmail/Googlemail local-part rules.
`blacklisted_chars` - if set to a string, the validator will reject emails whose local part contains any character in the string. The string is used as a RegExp character class fragment, so RegExp-special characters should be escaped.
`host_blacklist` - if set to an array of strings or RegExp objects, and the lower-cased host after the `@` symbol matches any entry, validation fails.
`host_whitelist` - if set to a non-empty array of strings or RegExp objects, and the lower-cased host after the `@` symbol matches none of the entries, validation fails. **isEmpty(str [, options])** | check if the string has a length of zero.

`options` is an object which defaults to `{ ignore_whitespace: false }`. **isEthereumAddress(str)** | check if the string is an [Ethereum][Ethereum] address. Does not validate address checksums. **isFloat(str [, options])** | check if the string is a float.

`options` is an object which can contain the keys `min`, `max`, `gt`, and/or `lt` to validate the float is within boundaries (e.g. `{ min: 7.22, max: 9.55 }`) it also has `locale` as an option.

`min` and `max` are equivalent to 'greater or equal' and 'less or equal', respectively while `gt` and `lt` are their strict counterparts.

`locale` determines the decimal separator and is one of `['ar', 'ar-AE', 'ar-BH', 'ar-DZ', 'ar-EG', 'ar-IQ', 'ar-JO', 'ar-KW', 'ar-LB', 'ar-LY', 'ar-MA', 'ar-QA', 'ar-QM', 'ar-SA', 'ar-SD', 'ar-SY', 'ar-TN', 'ar-YE', 'bg-BG', 'cs-CZ', 'da-DK', 'de-DE', 'en-AU', 'en-GB', 'en-HK', 'en-IN', 'en-NZ', 'en-US', 'en-ZA', 'en-ZM', 'eo', 'es-ES', 'fr-CA', 'fr-FR', 'hu-HU', 'it-IT', 'nb-NO', 'nl-NL', 'nn-NO', 'pl-PL', 'pt-BR', 'pt-PT', 'ru-RU', 'sl-SI', 'sr-RS', 'sr-RS@latin', 'sv-SE', 'tr-TR', 'uk-UA']`. Locale list is `validator.isFloatLocales`. diff --git a/src/lib/isEmail.js b/src/lib/isEmail.js index abe465052..1393ece26 100644 --- a/src/lib/isEmail.js +++ b/src/lib/isEmail.js @@ -6,6 +6,43 @@ import isFQDN from './isFQDN'; import isIP from './isIP'; import merge from './util/merge'; +/** + * @typedef {string|RegExp} EmailHostMatcher + */ + +/** + * Options supported by isEmail. + * + * Every property is optional. When a property is omitted or set to undefined, + * isEmail falls back to the value described for that property. + * + * @typedef {Object} IsEmailOptions + * @property {boolean} [allow_display_name=false] - Accept + * `Display Name ` input. + * @property {boolean} [require_display_name=false] - Require + * `Display Name ` input. + * @property {boolean} [allow_utf8_local_part=true] - Allow UTF-8 characters + * in the local part before the `@` symbol. + * @property {boolean} [require_tld=true] - Require the domain to include a + * top-level domain unless an allowed IP domain is supplied. + * @property {boolean} [allow_ip_domain=false] - Allow the domain to be an IP + * address, including bracket-wrapped IP literals. + * @property {boolean} [allow_underscores=false] - Allow underscores in the + * domain part. + * @property {boolean} [domain_specific_validation=false] - Apply additional + * provider-specific checks, currently including Gmail username rules. + * @property {string} [blacklisted_chars] - Defaults to ''. Reject local parts + * containing any character from this RegExp character class fragment. + * @property {boolean} [ignore_max_length=false] - Skip standard email, + * local-part, domain, and domain-label length checks. + * @property {EmailHostMatcher[]} [host_blacklist] - Defaults to []. Reject + * emails whose lower-cased host matches one of these strings or regular + * expressions. + * @property {EmailHostMatcher[]} [host_whitelist] - Defaults to []. Require + * the lower-cased host to match one of these strings or regular expressions + * when non-empty. + */ + const default_email_options = { allow_display_name: false, allow_underscores: false, @@ -32,7 +69,8 @@ const defaultMaxEmailLength = 254; /** * Validate display name according to the RFC2822: https://tools.ietf.org/html/rfc2822#appendix-A.1.2 - * @param {String} display_name + * @param {string} display_name + * @returns {boolean} whether the display name is valid. */ function validateDisplayName(display_name) { const display_name_without_quotes = display_name.replace(/^"(.+)"$/, '$1'); @@ -61,6 +99,13 @@ function validateDisplayName(display_name) { return true; } +/** + * Check if a string is an email address. + * + * @param {string} str - The string to validate. + * @param {IsEmailOptions} [options] - Optional validation settings. + * @returns {boolean} whether the string is a valid email address. + */ export default function isEmail(str, options) { assertString(str); options = merge(options, default_email_options);