NPMGithub

Email

Valid8r provides a comprehensive validator to validate email to different kinds of conditions that can be either customized globally or provided on every validation.

Valid8r covers all the basic as well as advanced email validations that covers 99% edge cases

Start by importing valid8r into your file:

import valid8r from '@c4code/valid8r';

Configuration Options

Valid8r email validator provides handful of options to best meet your requirements and validation needs, the options that can be configured in email validator are:

import valid8r from '@c4code/valid8r';

const input: string = "john32@gmail.com";

// The configuration can be defaulted globally
valid8r.email(input, {
  safe: false, // boolean
  noSpChars: true, // boolean
  startWithNum: false, // boolean
  endWithNum: false, // boolean
  minLen: 6, // number
  maxLen: 254, // number
  allowedDomains: ["*"], // string[]
  allowDisposables: true, // boolean
  customDisposables: 
    [ /* defaults all the popular disposable domain providers */], // string[]
  noLeading: true, // boolean
  noTrailing: true, // boolean
  caseSensitive: false, // boolean
  throwErrorsAs: "throw-all", // "throw-first" | "throw-last" | "throw-all",
  /*
  "throw-first" => Throws or returns the first error encountered,
  "throw-last" => Throws or returns the last error encountered,
  "throw-all" => Throws or returns all errors in a Array of string
  */
}); // the second argument is optional

The allowedDomains field accepts domains that should be allowed in the email address, ex.

allowedDomains: ['gmail.com', 'outlook.com']; // Accepts email from these domains

However, sometimes we need email addresses from a domain that have only specific source or TLD ( top-level domain ), you can set wildcards in allowedDomains as well to specify from which source or TLD the email is allowed

import valid8r from '@c4code/valid8r';

// Your input's value
const input2: string = "smithjones@outlook.com";

valid8r.email(input, {
    allowedDomains: ['*']
}); // Valid

valid8r.email(input, {
    allowedDomains: ['*.com']
}); // Valid

valid8r.email(input, {
    allowedDomains: ['outlook.*']
}); // Valid

valid8r.email(input, {
    allowedDomains: ['gmail.*']
}); // throws EmailValidationFailed error

The Configuration can be globally set for all the validators in your project, know more?

Basic Usage

Here's how we can use the email validator in it's most basic manner:

Start by importing valid8r:

import valid8r from '@c4code/valid8r';
import valid8r from '@c4code/valid8r';

// Your input's value
const input2: string = "sm#thjones@outlook.com";
valid8r.email(input); // throws EmailValidationFailed error

Safe handling

By default, all the validations in valid8r works on unsafe flag, meaning if any of the validation fails it will throw an Error.

However, if you don't want it to throw any error but return them. set the safe flag to true.

import valid8r from '@c4code/valid8r';

// Your input's value
const input2: string = "sm#thjones@outlook.com";
const [isValid, errors] = valid8r.email(input, { safe: true });

if (!isValid) {
    console.log(errors); 
    // [{ noSpChars: "Email should not contain any sp. characters other than . and @, found #." }]
}

Error Messages

If you don't like the default error message and want to set a custom error message for any specific fields, pass an object as a third argument of the email function:

import valid8r from '@c4code/valid8r';

// Your input's value
const input2: string = "sm#thjones@outlook.com";
const [isValid, errors] = valid8r.email(input, {
    safe: true
}, {
    noSpChars: "Special Characters are not allowed!"
});

if (!isValid) {
    console.log(errors); 
    // [{ noSpChars: "Special Characters are not allowed!" }]
}

Error Message Options

Valid8r email validator provides handful of options to configure error messages to best fit your project requirements

import valid8r from '@bitbybit/valid8r';

const input: string = "william.j@hotmail.com";

// The configuration can be defaulted globally
valid8r.email(input, { /* Field Configurations */ }, {
  format: 
    "Invalid Email Format.", // string
  noSpChars:
    "Email should not contain any sp. characters other than {allowedSpChars}, found {encounteredSpChar}.", // string
  startWithNum: 
    "Email should not start with a number.", // string
  endWithNum: 
    "Email should not end with a number.", // string
  minLen: 
    "Email must be at least {minLen} characters long.", // string
  maxLen: 
    "Email must not exceed {maxLen} characters.", // string
  allowedDomains: 
    "Email's domain must be one of: {allowedDomains}", // string
  allowDisposables: 
    "Disposable email addresses are not allowed.", // string
  noLeading: 
    "Email should not have leading spaces.", // string
  noTrailing: 
    "Email should not have trailing spaces.", // string
  caseSensitive: 
    "Email should be in lowercase.", // string
}); // the second and third argument is optional

All the options are optional, if passed will be used as the configuration for that specific validator

The Error messages can be globally set for all the validators in your project, know more?

PreviousNameNextPhone

Last updated