> ## Documentation Index
> Fetch the complete documentation index at: https://flex-fields.bjanczak.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Examples target Filament 5. Verify optional dependencies before configuring integrations.
> Upload transfer completion, permanent storage and record acceptance are separate milestones. Native and Spatie image conversions retain the original.

# CountryMapField

> Select ISO countries on an SVG world map synchronized with a searchable country dropdown.

<video autoPlay muted loop playsInline controls preload="metadata" src="https://mintcdn.com/flex-fields/DK_1kkuwd6AOeCzB/art/previews/country-map-field-motion.mp4?fit=max&auto=format&n=DK_1kkuwd6AOeCzB&q=85&s=d27c02e26ed852d25a0904e75b8305f7" poster="/art/previews/country-map-field.webp" width="1920" height="1080" aria-label="CountryMapField — FLEX Fields demonstration">
  [Watch the CountryMapField demonstration (MP4).](https://flex-fields.bjanczak.com/art/previews/country-map-field-motion.mp4)
</video>

`CountryMapField` combines a world map and country selector. It needs no geographic map SDK or map-provider token.

## Multiple countries

```php theme={"theme":{"light":"github-light","dark":"github-dark"}}
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\CountryMapField;

CountryMapField::make('markets')
    ->countries(['BR', 'MX', 'AR', 'CL', 'PL', 'DE'])
    ->countryGroups([
        'Latin America' => ['BR', 'MX', 'AR', 'CL'],
        'Europe' => ['PL', 'DE'],
    ])
    ->mapHeight(320)
    ->mapColor('#22c55e')
    ->default(['BR', 'MX']);
```

## State and validation

Default state is an array of uppercase ISO alpha-2 codes. `multiple(false)` changes it to a code or null and hides bulk groups. `countries(null)` admits the full country catalog; an explicit list constrains map and dropdown. Named group countries must belong to the allowed set. There may be at most 32 named groups. Submitted selection size is bounded by the unique allowed country catalog; duplicates and unsupported codes are rejected. Field disabled/readOnly policies block both SVG and list edits.

## Map and list interactions

CountryMap uses the shared SelectField engine: rich flags/names, chips, searching, virtualization/menu lifecycle, desktop dropdown and mobile sheet. Names sort with the current locale's ICU collator when available. Country group checkboxes show none/partial/all selected states and counts; their design/animation uses the same indicator asset as ChoiceCheckboxCards. Group membership and individual choices update the same entangled ISO state. Map regions support Enter/Space activation; list selection provides a keyboard alternative. Zoom/pan never changes selected values.

`mapHeight()` accepts 200–800 px; `mapColor()` accepts #RRGGBB. The embedded simplified dataset has 173 outlines. Countries/territories without an outline remain selectable in the full list. This map is a selection aid, not an authoritative border/geopolitical dataset. Outlines come from the MIT jsvectormap 1.7.0 world dataset (verified package integrity), with attribution/license in `resources/licenses/jsvectormap-world-LICENSE.txt`. No jsvectormap rendering library code or third-party editor code is used.

The world surface itself needs no map API, tile requests, geolocation or WebGL. Country flags use the shared local flag assets also used by [CountryField](https://flex-fields.bjanczak.com/docs/countryfield.md) and [PhoneField](https://flex-fields.bjanczak.com/docs/phonefield.md). Geographic provider options in the [shared map reference](https://flex-fields.bjanczak.com/docs/location-v4.md) apply to the separate map components, not this SVG country map.

The playground configures three explicit bulk groups (Latin America, Sub-Saharan Africa, Central Asia). Applications define their own `countryGroups()` policies; region membership is not assumed by the field. Group rows and country rows use the same checkbox column and selection indicator; counts show selected/total. A Countries heading reuses the shared Select group heading style. Bulk toggles remain keyboard accessible.

## Single country

```php theme={"theme":{"light":"github-light","dark":"github-dark"}}
CountryMapField::make('market')
    ->multiple(false)
    ->countries(['PL', 'DE', 'FR'])
    ->default('PL');
```

Single selection stores an uppercase ISO alpha-2 string such as `PL`, or `null`. Use a scalar model attribute for this mode. Multiple selection stores an array of ISO codes; use a JSON column with an Eloquent `array` cast. Labels, translated names and SVG paths are not the saved value.

## Appearance and camera

| Method | Purpose |
| - | - |
| `mapHeight(320)` | Set the SVG viewport height, 200–800 pixels. |
| `mapColor('#22c55e')` | Set the selection color using #RRGGBB. |
| `mapZoomRange(1, 6)` | Configure the country map's zoom range. |
| `mapAnimationDuration(180)` | Configure camera transition duration. |
| `mapScrollZoom()` | Enable wheel zoom, disabled by default. |
| `mapTooltips(false)` | Hide map region tooltips. |

## Related components

* [CountryField](https://flex-fields.bjanczak.com/docs/countryfield.md) — the country list without an SVG map.
* [MapPickerField](https://flex-fields.bjanczak.com/docs/mappickerfield.md) — a geographic address/location picker.
* [MapZonesField](https://flex-fields.bjanczak.com/docs/map-zones.md) — application-defined geographic areas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.