PhoneField

Collect international phone numbers with a searchable country selector, local flags, dial codes, normalization and PHP validation.

← Back to Table of Contents

Summary

International phone input with searchable country picker, local circle flags, libphonenumber validation, and structured state (country, national, e164).

Class	Bjanczak\FilamentFlexFields\Filament\Forms\Components\PhoneField
State type	array<country: string, national: string, e164: string>
FieldType	phone
Playground	phone-field slug in Flex Fields playground

Basic usage

use Bjanczak\FilamentFlexFields\Filament\Forms\Components\PhoneField;

PhoneField::make('phone')
    ->label('Mobile number')
    ->defaultCountry('PL')
    ->required();

PhoneField::make('contact_phone')
    ->countries(['PL', 'DE', 'GB', 'US'])
    ->mobileOnly()
    ->browserLocaleDefault()
    ->browserLocaleSortFirst();

Load from an E.164 string on edit:

PhoneField::make('phone')
    ->afterStateHydrated(function (PhoneField $component, mixed $state): void {
        if (is_string($state) && filled($state)) {
            $component->state($component->normalizeState($state));
        }
    });

Store only E.164 in the database:

PhoneField::make('phone')
    ->dehydrateStateUsing(fn (array $state): ?string => filled($state['e164'] ?? null)
        ? $state['e164']
        : null);

To store the default composite value, use a JSON column with an Eloquent array cast. Its country key is a code such as PL or DE, never the country label. Country names, flag URLs and dropdown descriptions are not persisted. Saving only E.164 is optional, using the dehydration callback above.

State format

Key	Description	Example
country	Uppercase telephone region code (ISO alpha-2, or supported AC / TA / XK)	PL
national	After a successful normalizeState(), libphonenumber NATIONAL formatting by default (spaces / punctuation). Opt-in nationalDigitsOnly() / nationalFormat('digits') stores digits only. The Alpine as-you-type UI keeps digits internally and formats for display.	512 345 678 or 512345678
e164	E.164 when the number is valid; otherwise may be empty or a provisional dial+digits string	[phone]
international / rfc3966	Optional — when includeFormats([...]) is enabled	[phone], tel:[phone]
carrier / geo / timezones / type	Optional — when includeMetadata([...]) is enabled (PHP libphonenumber mappers; zero JS cost)	Orange, Poland, ["Europe/Warsaw"], MOBILE

On hydrate and dehydrate, normalizeState() runs automatically. A plain string state (e.g. [phone]) is parsed on hydrate. Default national stays NATIONAL-formatted for BC; use digits-only or e164 when you need machine-friendly values.

Validation

Behaviour	Detail
Built-in	Checks submitted region and number shape before normalization, then validates with libphonenumber
required()	national must not be empty
mobileOnly()	Sugar for allowTypes([MOBILE]) (also accepts FIXED_LINE_OR_MOBILE unless strictTypes())
fixedLineOnly()	Sugar for allowTypes([FIXED_LINE])
allowTypes([...])	Explicit libphonenumber types (MOBILE, VOIP, …)
validateForRegion()	isValidNumberForRegion against the selected country
Filament required rule	Overridden to nullable — validation handled by custom rule

Do not combine mobileOnly() and fixedLineOnly() on the same field — throws InvalidArgumentException. Prefer allowTypes() for multi-type rules.

Configuration API

variant(string|Closure $variant)

Visual style shared with FlexTextInput. Values: primary (default), secondary, flat, soft.

->variant('secondary')

size(string|ControlSize|Closure $size)

Control height. See Control size. Default: md.

PhoneField::make('field_name')
    ->size('md');

defaultCountry(string|Closure $countryCode)

ISO country code when no country is selected. Default: PL. Falls back to first allowed country or US.

PhoneField::make('field_name')
    ->defaultCountry('value');

countries(array|Closure|null $countries)

Whitelist of ISO codes. null = all countries (minus exceptCountries).

->countries(['PL', 'DE', 'FR'])

exceptCountries(array|Closure $countries)

Blacklist applied after the whitelist. Default: [].

PhoneField::make('field_name')
    ->exceptCountries(['value1', 'value2']);

searchable(bool|Closure $condition = true)

Show search input in the country dropdown. Default: true.

PhoneField::make('field_name')
    ->searchable(true);

suffixIcon(string|BackedEnum|Htmlable|Closure|bool|null $icon = null)

Trailing icon. Pass false to hide. Pass an icon name to set a custom icon. Default: config filament-flex-fields.ui.phone_suffix_icon or GravityIcon::Smartphone.

->suffixIcon(false)
->suffixIcon('heroicon-o-device-phone-mobile')

internationalPrefix(bool|Closure $condition = true)

Show dial code prefix next to the national input. Default: true.

PhoneField::make('field_name')
    ->internationalPrefix(true);

mobileOnly(bool|Closure $condition = true)

Restrict to mobile numbers.

PhoneField::make('field_name')
    ->mobileOnly(true);

fixedLineOnly(bool|Closure $condition = true)

Restrict to fixed-line numbers.

PhoneField::make('field_name')
    ->fixedLineOnly(true);

browserLocaleDefault(bool|Closure $condition = true)

When enabled and national number is empty, pre-select country from Accept-Language / browser locale.

PhoneField::make('field_name')
    ->browserLocaleDefault(true);

browserLocaleSortFirst(bool|Closure $condition = true)

Sort country list with browser locale country first.

PhoneField::make('field_name')
    ->browserLocaleSortFirst(true);

locale(string|Closure|null $locale)

Language for country names in the picker (en → Poland, pl → Polska). Defaults to app()->getLocale(). CountryField and PhoneField share the same translation resolver: package overrides first, then PHP ICU regional names, then English fallback. Names are identical on the initial render and in the dropdown.

PhoneField::make('phone')->locale('pl');

placeholder(string|Closure|null $placeholder)

Inherited from Filament HasPlaceholder. When omitted, the field uses a libphonenumber national example for the default country (and mobile/fixed type when constrained), otherwise the package language string.

PhoneField::make('field_name')
    ->placeholder('Enter value...');

allowTypes(array|Closure|null $types)

Restrict accepted libphonenumber number types (PhoneNumberType cases or names like MOBILE, VOIP). When set, overrides mobileOnly() / fixedLineOnly() sugar.

PhoneField::make('phone')->allowTypes(['MOBILE', 'VOIP']);

strictTypes(bool|Closure $condition = true)

Do not auto-accept FIXED_LINE_OR_MOBILE alongside MOBILE / FIXED_LINE.

validateForRegion(bool|Closure $condition = true)

Require isValidNumberForRegion() for the selected country (stricter than global isValidNumber).

nationalFormat(PhoneNationalFormat|string|Closure $format) / nationalDigitsOnly()

Default national (BC). Digits-only is opt-in:

PhoneField::make('phone')->nationalDigitsOnly();

includeFormats(array|Closure $formats)

Add international and/or rfc3966 keys to dehydrated state (valid numbers only).

includeMetadata(array|Closure $metadata)

Add PHP-side carrier, geo, timezones, and/or type keys (valid numbers only). No JS / phone-lib budget impact.

readOnly(bool|Closure $condition = true)

Inherited from Filament CanBeReadOnly.

PhoneField::make('field_name')
    ->readOnly(true);

focusOutline(bool|Closure $condition = true)

Inherited from HasFieldFocusOutline.

PhoneField::make('field_name')
    ->focusOutline(true);

Public helper methods

Method	Returns	Description
getVariant()	string	Resolved variant
getAllowedCountryCodes()	list<string>|null	Whitelist or null
getExceptCountryCodes()	list<string>	Blacklist
getDefaultCountryCode()	string	Effective default region
isSearchable()	bool	Country search enabled
hasSuffixIcon()	bool	Suffix icon visible
showsInternationalPrefix()	bool	Dial prefix visible
isMobileOnly()	bool	Mobile validation
isFixedLineOnly()	bool	Fixed-line validation
shouldUseBrowserLocaleDefault()	bool	Browser locale default
shouldSortCountriesByBrowserLocale()	bool	Browser locale sort
getBrowserLocaleCountryCode()	string|null	Detected locale country
getCountriesMetadata()	list<array>	code, name, dial_code, flag_url
getCountrySelectOptions()	array	Options for internal select
getDefaultSuffixIcon()	string|BackedEnum|Htmlable	Default suffix icon
getSuffixIcon()	string|BackedEnum|Htmlable|null	Resolved suffix icon
normalizeState(mixed $state)	array	Canonical {country, national, e164}
getPhoneValidationMessage(array $state)	string|null	Error message or null
getWrapperClasses()	list<string>	CSS class list

FlexField schema config

Config key	Maps to
size	size()
variant	variant()
default_country	defaultCountry()
countries	countries()
except_countries	exceptCountries()
searchable	searchable()
suffix_icon	suffixIcon()
international_prefix	internationalPrefix()
mobile_only	mobileOnly()
fixed_line_only	fixedLineOnly()
allow_types	allowTypes()
strict_types	strictTypes()
validate_for_region	validateForRegion()
national_format	nationalFormat() / nationalDigitsOnly()
include_formats	includeFormats()
include_metadata	includeMetadata()
browser_locale_default	browserLocaleDefault()
browser_locale_sort_first	browserLocaleSortFirst()
locale	locale()

CSS classes

Class	Role
fff-phone-field	Root wrapper
fff-phone-field--{sm|md|lg}	Size modifier
fff-phone-field__country-trigger	Country picker button
fff-phone-field__country-menu	Teleported dropdown (is-positioned when open)
fff-phone-field__control	National number input area
fff-phone-field__dial-prefix	International prefix display

Shares FlexTextInput shell classes (fff-flex-text-input-field, variant modifiers).

Implementation notes

• Country dropdown uses x-teleport="body" to avoid overflow clipping.
• Depends on giggsey/libphonenumber-for-php for parsing and validation.
• Empty national number dehydrates to e164: '' regardless of partial dial prefix.

---

Playground

Slug: phone-field

Demo field	Shows
Default	Searchable country picker, E.164 validation
Restricted countries	Whitelist + mobile-only
Browser locale	browserLocaleDefault() + sort-first
Fixed line only	fixedLineOnly()
Except countries	exceptCountries()
Non-searchable / read-only	Full list searchable(false), readOnly()
Digits / region / enriched	nationalDigitsOnly(), validateForRegion(), formats + metadata
Allow types	allowTypes(['VOIP','MOBILE'])

/admin/flex-fields/phone-field — see Playground.

---

Related components

Component	When to use instead
CountryField	ISO country only — no phone number
FlexTextInput	Plain text without libphonenumber
FlexVerificationCode	OTP / SMS codes, not full numbers
AddressAutocompleteField	Structured address with optional phone

---

Country catalog and local flags

The country picker follows libphonenumber’s supported telephone regions, including AC, TA and XK. It is intentionally separate from CountryField’s default 249-entry ISO address catalog: some ISO territories do not have a supported calling-code region. The exact telephone list follows the installed libphonenumber metadata version. countries() and exceptCountries() constrain both selection and locale detection.

Both pickers share one country-flags asset publication. All supported flags are materialized local SVG files, including territories whose upstream files are aliases. No external flag CDN is contacted. Publish them through the standard installation steps:

php artisan filament:assets
php artisan fff:assets:publish

See Installation for deployment and asset checks. Country names and metadata are cached within the request; no browser-side country-name library or full flag preloading is required.

The current installed libphonenumber metadata contains 245 telephone regions, while CountryField defaults to 249 ISO entries. Telephone regions are not a superset of the address catalog. Every supported region has a local flag and a calling prefix from libphonenumber, including shared prefixes such as +1. The prefix displayed by PhoneField follows the selected region.

Submitted state and server validation

Save through Filament’s validated getState() result. Validation rejects unknown or excluded region codes, country labels, structured country values, non-string national numbers, unsupported characters and excessive input. Malformed state can be rendered safely without raising a server error, but cannot pass validation. required() also rejects an empty national number.

The server derives E.164 from country and national; a forged client-side e164 cannot override it. Unrequested keys such as labels, flag URLs or enrichment are removed on dehydration. Enabled includeFormats() / includeMetadata() values are computed on the server and retained; submitted enrichment is never trusted. validateForRegion() additionally requires the parsed number to be valid for the selected region. This remains optional because several regions share calling codes.