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.| Class | Bjanczak\FilamentFlexFields\Filament\Forms\Components\CountryField |
| State type | string|null — ISO alpha-2 country code |
| Model cast | 'country_code' => 'string' |
| FieldType | country |
| Playground | country-field slug in Flex Fields playground |
Basic usage
Standard country picker
Whitelist and browser detection
State & validation
Stored value
State is a single uppercase ISO 3166-1 alpha-2 string.Validation rules
Built-in validation ensures the submitted code is in the resolved country list.| Rule | Detail |
|---|---|
nullable | Always (unless required()) |
in(...) | Value must match a configured ISO alpha-2 code |
Configuration API
All methods acceptClosure unless noted.
| Method | Type | Default | Description |
|---|---|---|---|
countries(array|Closure|null $countries) | Setup | null | Whitelist 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) | Setup | false | Pre-select from browser locale |
browserLocaleSortFirst(bool|Closure $condition = true) | Setup | false | Sort browser country to top of list |
showCountryCode(bool|Closure $condition = true) | Setup | false | Show ISO code (e.g. PL) next to name |
showDialCode(bool|Closure $condition = true) | Setup | false | Show international dial code (e.g. +48) |
searchable(bool|Closure $condition = true) | Setup | true | Show 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) | Setup | config | Border radius token |
countries() / exceptCountries()
Limit the list to specific markets:
showDialCode()
Useful for address forms where phone context is helpful:
Real-world examples
Shipping address form
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.
Related components
| Component | When to use instead |
|---|---|
| PhoneField | For picking a country as part of a phone number input |
| TimezoneField | For picking a timezone instead of a country |
| AddressAutocompleteField | For full address search with Mapbox |
CSS classes (reference)
| Class | Role |
|---|---|
fff-country-field | Root wrapper |
fff-country-field--{sm|md|lg} | Size modifier |
fff-country-field__trigger | Picker button |
fff-country-field__flag | Circle flag image |
fff-country-field__menu | Dropdown panel |
fff-country-field__search | Search input |
Performance
| Mechanism | What it does |
|---|---|
| Flag CDN | Optimized SVG flags served via a fast CDN for minimal bundle size |
| Memoized Metadata | Country lists and translations are cached per-request |
| Teleport | Uses x-teleport="body" to avoid overflow clipping in modals |