International phone input
/**
* 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.