Skip to main content
← Back to Table of Contents

Summary

Searchable country picker with circle flags. Stores a single ISO 3166-1 alpha-2 code. Uses the full country list (~255 codes) with optimized flag assets.
ClassBjanczak\FilamentFlexFields\Filament\Forms\Components\CountryField
State typestring|null — ISO alpha-2 country code
Model cast'country_code' => 'string'
FieldTypecountry
Playgroundcountry-field slug in Flex Fields playground

Basic usage

Standard country picker

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

CountryField::make('country')
    ->label('Country')
    ->defaultCountry('PL')
    ->required();

Whitelist and browser detection

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

CountryField::make('shipping_country')
    ->countries(['PL', 'DE', 'GB', 'US', 'FR'])
    ->exceptCountries(['RU'])
    ->showCountryCode()
    ->browserLocaleDefault()
    ->browserLocaleSortFirst();

State & validation

Stored value

State is a single uppercase ISO 3166-1 alpha-2 string.
$record->country_code; // string|null — e.g. "PL", "US", "DE"

Validation rules

Built-in validation ensures the submitted code is in the resolved country list.
RuleDetail
nullableAlways (unless required())
in(...)Value must match a configured ISO alpha-2 code

Configuration API

All methods accept Closure unless noted.
MethodTypeDefaultDescription
countries(array|Closure|null $countries)SetupnullWhitelist of ISO alpha-2 codes
exceptCountries(array|Closure $countries)Setup[]Blacklist of ISO alpha-2 codes
defaultCountry(string|Closure|null $countryCode)Setup'PL'Fallback ISO code
browserLocaleDefault(bool|Closure $condition = true)SetupfalsePre-select from browser locale
browserLocaleSortFirst(bool|Closure $condition = true)SetupfalseSort browser country to top of list
showCountryCode(bool|Closure $condition = true)SetupfalseShow ISO code (e.g. PL) next to name
showDialCode(bool|Closure $condition = true)SetupfalseShow international dial code (e.g. +48)
searchable(bool|Closure $condition = true)SetuptrueShow search input in dropdown
variant(string|Closure $variant)Setup'primary'Visual style: primary, secondary, flat, soft
size(string|ControlSize|Closure $size)Setup'md'Control size: sm, md, lg
rounding(string|Closure|null $rounding)SetupconfigBorder radius token

countries() / exceptCountries()

Limit the list to specific markets:
CountryField::make('country')
    ->countries(['US', 'CA', 'MX']);

showDialCode()

Useful for address forms where phone context is helpful:
CountryField::make('country')->showDialCode();

Real-world examples

Shipping address form

public static function form(Form $form): Form
{
    return $form->schema([
        CountryField::make('shipping_country')
            ->label('Delivery Country')
            ->countries(config('app.shipping_countries'))
            ->browserLocaleDefault()
            ->required(),
    ]);
}

Multi-language support

Country names are automatically translated based on the application locale using the package’s built-in translation files.

Playground

/admin/flex-fields-playground/country-field See Playground for setup.
ComponentWhen to use instead
PhoneFieldFor picking a country as part of a phone number input
TimezoneFieldFor picking a timezone instead of a country
AddressAutocompleteFieldFor full address search with Mapbox

CSS classes (reference)

ClassRole
fff-country-fieldRoot wrapper
fff-country-field--{sm|md|lg}Size modifier
fff-country-field__triggerPicker button
fff-country-field__flagCircle flag image
fff-country-field__menuDropdown panel
fff-country-field__searchSearch input

Performance

MechanismWhat it does
Flag CDNOptimized SVG flags served via a fast CDN for minimal bundle size
Memoized MetadataCountry lists and translations are cached per-request
TeleportUses x-teleport="body" to avoid overflow clipping in modals