Special Field

Phone

An international phone input with a country selector that stores the number as an E.164 string.

View as Markdown
stable
phonetelinternationale164input

International phone input

Select your country and enter your number

/**
 * Phone Field Demo
 */
import { Form, FormBuilder } from '@saastro/forms';
import { FormProvider } from '@/components/FormProvider';
import { TooltipProvider } from '@/components/ui/tooltip';

const config = FormBuilder.create('phone-demo')
  .layout('manual')
  .columns(12)
  .addField('phone', (f) =>
    f
      .type('phone')
      .label('Phone number')
      .helperText('Select your country and enter your number')
      .placeholder('612 345 678')
      .prop('defaultCountry', 'US')
      .optional()
      .columns({ default: 12 }),
  )
  .addStep('main', ['phone'])
  .build();

export default function PhoneDemo() {
  const handleSubmit = (data: Record<string, unknown>) => {
    console.log('Form submitted:', data);
  };

  return (
    <TooltipProvider>
      <FormProvider>
        <Form config={config} onSubmit={handleSubmit} className="space-y-6" />
      </FormProvider>
    </TooltipProvider>
  );
}

Overview

phone is a country <select> (ISO code + dial code) paired with a national-number <input type="tel">. The dial code and number are combined into a single E.164 value on every change.

This is distinct from a plain tel text field: phone manages the country prefix for you.

Value

The submitted value is a single E.164 string (valueKind: 'string'), e.g. "+34612345678". An existing E.164 value is best-effort parsed back to pre-fill the controls.

Usage

import { FormBuilder } from '@saastro/forms';

const config = FormBuilder.create('contact')
  .addField('phone', (f) =>
    f.type('phone').label('Phone number').prop('defaultCountry', 'US'),
  )
  .addStep('main', ['phone'])
  .build();

defaultCountry (and countries) have no fluent method — set them with .prop().

Props

Prop Type Default Description
defaultCountry string 'US' ISO country code preselected
countries Array<{ code: string; dialCode: string; name: string }> bundled list Override the selectable countries
placeholder string – National-number input placeholder

Using the phone helpers outside a form

The field’s E.164 logic is exported, so a server handler, a CRM import or a custom control can build and read the same value the field submits.

import { DEFAULT_COUNTRIES, parseE164, toE164 } from '@saastro/forms';

toE164('34', '612 34 56 78'); // '+34612345678' — non-digits are stripped
toE164('34', '');             // ''              — no number, no value

parseE164('+34612345678', DEFAULT_COUNTRIES);
// { country: { code: 'ES', dialCode: '34', name: 'Spain' }, nationalNumber: '612345678' }

parseE164('612345678', DEFAULT_COUNTRIES);
// { country: undefined, nationalNumber: '' } — without a leading '+' it is not E.164
Export Signature Notes
toE164 (dialCode: string, nationalNumber: string) => string dialCode without +. Returns '' when the number has no digits.
parseE164 (value: string, countries: Country[]) => { country: Country | undefined; nationalNumber: string } Best-effort: matches the longest dial code first, so a short code like 1 never shadows a longer one that starts with it. Countries that share a code (US and Canada, 1) resolve to the first one in the list.
DEFAULT_COUNTRIES Country[] The compact list the field uses when countries is not set (49 entries, dialCode without +). Spread it to extend it rather than retyping it.

Country is { code: string; dialCode: string; name: string }, the same shape the countries prop takes.