Skip to content
Telixon

Strict mode

Composes: parsePhoneNumber + ValidationError

Strict mode restricts validity to one region: a number that is valid elsewhere in the world reports isValid() === false unless it is valid in defaultRegion. Validity is an accepting state, and every ValidationError variant is a named way of not being in one; strict narrows the accepting states to those that belong to defaultRegion.

import { ensureEngineReady, parsePhoneNumber } from '@telixon/core';


await ensureEngineReady();


// A valid US number entering a Canada-only form.
const outside = parsePhoneNumber('+1 212 555 0198', {
  defaultRegion: 'CA',
  strict: true,
});


outside.isValid(); // false
outside.getNumberType(); // 'UNKNOWN'
outside.getValidationError(); // { kind: 'PATTERN_MISMATCH' }


// The same input without strict is a valid US number.
parsePhoneNumber('+1 212 555 0198', { defaultRegion: 'CA' }).isValid(); // true


// A Canadian number passes strict validation.
const inside = parsePhoneNumber('604 555 0199', {
  defaultRegion: 'CA',
  strict: true,
});


inside.isValid(); // true
inside.getNumberType(); // 'FIXED_LINE_OR_MOBILE'
inside.formatE164(); // '+16045550199'

The US number resolves normally but fails validation against Canada; the Canadian number is valid and formats to E.164. Strict isValid() is the analog of Google libphonenumber’s isValidNumberForRegion; if you are porting code that calls it, see Migrate from Google libphonenumber.

1. Turn on strict together with defaultRegion

Section titled “1. Turn on strict together with defaultRegion”

Strict is off by default and has no effect without defaultRegion, because there is no region to restrict to.

// No defaultRegion, so strict changes nothing.
parsePhoneNumber('+1 212 555 0198', { strict: true }).isValid(); // true

Use it when the product accepts numbers from exactly one country: single-country signup forms, compliance forms that require a domestic number, carrier or banking flows tied to one national numbering plan.

2. Branch on isValid and the validation error

Section titled “2. Branch on isValid and the validation error”

A strict rejection of a number that is valid in another region surfaces as { kind: 'PATTERN_MISMATCH' }: the digits are length-possible, but they match no pattern inside defaultRegion. All other ValidationError variants keep their usual meaning under strict.

const number = parsePhoneNumber(rawInput, { defaultRegion: 'CA', strict: true });


if (!number.isValid()) {
  const error = number.getValidationError();
  // error.kind === 'PATTERN_MISMATCH' for the '+1 212 555 0198' input above
  showFieldError(error);
  return;
}

To turn each variant into user-facing copy, follow Show form errors.

3. Know what strict does not change

Section titled “3. Know what strict does not change”

Strict restricts isValid() and getNumberType() to defaultRegion. Every other query ignores it.

Query Under strict
isValid() Restricted to defaultRegion
getNumberType() Restricted to defaultRegion; 'UNKNOWN' for numbers valid only elsewhere
getRegion() Ignores strict; reports the resolved region
isPossible(), isPossibleWithReason() Ignore strict
formatE164() and the other format* methods Ignore strict 
outside.getRegion(); // 'US'            (resolution ignores strict)
outside.isPossible(); // true           (possibility ignores strict)
outside.formatE164(); // '+12125550198' (formatting ignores strict)

Because formatting ignores strict, a rejected number still formats; guard writes to your database behind isValid(), as in Validate on submit.

4. Use isValidForRegion for one-off checks

Section titled “4. Use isValidForRegion for one-off checks”

Strict applies the restriction to every isValid() and getNumberType() call on the instance. When only a single check needs it, call isValidForRegion on a non-strict parse instead.

const number = parsePhoneNumber('+1 212 555 0198');


number.isValid(); // true
number.isValidForRegion('US'); // true
number.isValidForRegion('CA'); // false

Strict in the input controllers

Section titled “Strict in the input controllers”

parsePhoneNumber and the input controller are the same shared resolve layer, queried in batch versus per keystroke, so the strict?: boolean config field on createNationalInputController and createInternationalInputController behaves exactly as described here.

Next steps

Section titled “Next steps”