or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

as-you-type-formatter.md enums-and-types.md index.md phone-number-util.md short-number-info.md

tile.json

As You Type Formatter

The AsYouTypeFormatter provides real-time phone number formatting as users input digits, showing the expected format as they type. This is particularly useful for creating intuitive phone number input fields in web forms and mobile applications.

Capabilities

AsYouTypeFormatter Class

A specialized tool that shows the formatting progress as it attempts to discover the right format for the given number. It requires registering every keystroke (input digit) on a new instance.

/**
 * Real-time phone number formatter that formats as users type
 * @constructor Creates a new formatter instance for a specific region
 */
class AsYouTypeFormatter {
  /**
   * Create a new AsYouTypeFormatter for the specified region
   * @param {string} regionCode - ISO 3166-1 alpha-2 region code (e.g., 'US', 'GB')
   */
  constructor(regionCode: string);
}

Input Processing

Process individual digits and characters to build formatted phone numbers progressively.

/**
 * Input a single digit and get the current formatted result
 * @param {string} digit - Single digit, separator, or formatting character to input
 * @returns {string} The current formatted phone number string
 */
inputDigit(digit: string): string;

/**
 * Input a digit and remember the cursor position for advanced editing scenarios
 * @param {string} digit - Single digit, separator, or formatting character to input
 * @returns {string} The current formatted phone number string with position tracking
 */
inputDigitAndRememberPosition(digit: string): string;

State Management

Control the formatter's state and reset for new input sessions.

/**
 * Clear all input digits from the formatter instance and reset to initial state
 * @returns {void}
 */
clear(): void;

Usage Examples

Basic Progressive Formatting

const AsYouTypeFormatter = require('google-libphonenumber').AsYouTypeFormatter;

// Create formatter for US numbers
const formatter = new AsYouTypeFormatter('US');

// Input digits progressively
console.log(formatter.inputDigit('2')); // => "2"
console.log(formatter.inputDigit('0')); // => "20" 
console.log(formatter.inputDigit('2')); // => "202"
console.log(formatter.inputDigit('-')); // => "202-"
console.log(formatter.inputDigit('4')); // => "202-4"
console.log(formatter.inputDigit('5')); // => "202-45"
console.log(formatter.inputDigit('6')); // => "202-456"
console.log(formatter.inputDigit('-')); // => "202-456-"
console.log(formatter.inputDigit('1')); // => "202-456-1"
console.log(formatter.inputDigit('4')); // => "202-456-14"
console.log(formatter.inputDigit('1')); // => "202-456-141"
console.log(formatter.inputDigit('4')); // => "202-456-1414"

// Reset for new number
formatter.clear();

International Number Formatting

const AsYouTypeFormatter = require('google-libphonenumber').AsYouTypeFormatter;

// Format UK numbers
const ukFormatter = new AsYouTypeFormatter('GB');

console.log(ukFormatter.inputDigit('0')); // => "0"
console.log(ukFormatter.inputDigit('2')); // => "02"
console.log(ukFormatter.inputDigit('0')); // => "020"
console.log(ukFormatter.inputDigit('7')); // => "020 7"
console.log(ukFormatter.inputDigit('9')); // => "020 79"
console.log(ukFormatter.inputDigit('4')); // => "020 794"
console.log(ukFormatter.inputDigit('6')); // => "020 7946"
console.log(ukFormatter.inputDigit('0')); // => "020 7946 0"
console.log(ukFormatter.inputDigit('9')); // => "020 7946 09"
console.log(ukFormatter.inputDigit('5')); // => "020 7946 095"
console.log(ukFormatter.inputDigit('8')); // => "020 7946 0958"

Handling Non-Digit Characters

The formatter accepts and processes formatting characters like dashes, spaces, and parentheses:

const formatter = new AsYouTypeFormatter('US');

// Mix of digits and formatting characters
console.log(formatter.inputDigit('(')); // => "("
console.log(formatter.inputDigit('2')); // => "(2"
console.log(formatter.inputDigit('0')); // => "(20"
console.log(formatter.inputDigit('2')); // => "(202"
console.log(formatter.inputDigit(')')); // => "(202)"
console.log(formatter.inputDigit(' ')); // => "(202) "
console.log(formatter.inputDigit('4')); // => "(202) 4"
console.log(formatter.inputDigit('5')); // => "(202) 45"
console.log(formatter.inputDigit('6')); // => "(202) 456"
console.log(formatter.inputDigit('-')); // => "(202) 456-"
console.log(formatter.inputDigit('1')); // => "(202) 456-1"
console.log(formatter.inputDigit('4')); // => "(202) 456-14"
console.log(formatter.inputDigit('1')); // => "(202) 456-141"
console.log(formatter.inputDigit('4')); // => "(202) 456-1414"

Form Input Integration

Example integration with an HTML input field:

const AsYouTypeFormatter = require('google-libphonenumber').AsYouTypeFormatter;

function setupPhoneInput(inputElement, regionCode) {
  const formatter = new AsYouTypeFormatter(regionCode);
  let lastFormatted = '';
  
  inputElement.addEventListener('input', (event) => {
    const currentValue = event.target.value;
    
    // Handle backspace/deletion
    if (currentValue.length < lastFormatted.length) {
      formatter.clear();
      // Re-input all characters
      for (let i = 0; i < currentValue.length; i++) {
        formatter.inputDigit(currentValue.charAt(i));
      }
    } else {
      // Add new character
      const newChar = currentValue.charAt(currentValue.length - 1);
      formatter.inputDigit(newChar);
    }
    
    const formatted = formatter.inputDigit(''); // Get current state
    event.target.value = formatted;
    lastFormatted = formatted;
  });
}

// Usage
const phoneInput = document.getElementById('phone-input');
setupPhoneInput(phoneInput, 'US');

Implementation Notes

State Persistence

Each AsYouTypeFormatter instance maintains its own state. Create a new instance for each phone number input field, and reuse the same instance for progressive input on that field.

Region Context

The region code provided during construction determines the formatting rules and patterns used. Choose the appropriate region based on:

User's detected location
Form context (e.g., billing country)
User preference settings
Default to a primary region for your application

Character Handling

The formatter accepts:

Digits (0-9)
Common separators (-, space, parentheses)
International prefix indicators (+)
Extension indicators (x, ext, etc.)

Non-relevant characters are typically ignored or filtered out by the formatter's internal logic.

Performance Considerations

Create one formatter per input field
Call clear() when starting a new number entry
The formatter is optimized for single-character input sequences
Avoid recreating formatter instances unnecessarily