PhoneField - Filament Flex Fields

Summary

International phone input with searchable country picker, 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);

State format

Key	Description	Example
`country`	ISO 3166-1 alpha-2 region code	`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	`+48512345678`
`international` / `rfc3966`	Optional — when `includeFormats([...])` is enabled	`+48 512 345 678`, `tel:+48-512-345-678`
`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. +48 512 345 678) 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	Custom rule on normalized array; uses 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().

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-playground/phone-field — see Playground.

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

​Summary

​Basic usage

​State format

​Validation

​Configuration API

​variant(string|Closure $variant)

​size(string|ControlSize|Closure $size)

​defaultCountry(string|Closure $countryCode)

​countries(array|Closure|null $countries)

​exceptCountries(array|Closure $countries)

​searchable(bool|Closure $condition = true)

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

​internationalPrefix(bool|Closure $condition = true)

​mobileOnly(bool|Closure $condition = true)

​fixedLineOnly(bool|Closure $condition = true)

​browserLocaleDefault(bool|Closure $condition = true)

​browserLocaleSortFirst(bool|Closure $condition = true)

​locale(string|Closure|null $locale)

​placeholder(string|Closure|null $placeholder)

​allowTypes(array|Closure|null $types)

​strictTypes(bool|Closure $condition = true)

​validateForRegion(bool|Closure $condition = true)

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

​includeFormats(array|Closure $formats)

​includeMetadata(array|Closure $metadata)

​readOnly(bool|Closure $condition = true)

​focusOutline(bool|Closure $condition = true)

​Public helper methods

​FlexField schema config

​CSS classes

​Implementation notes

​Playground

​Related components