README

Adds a 'Country' field type for the Advanced Custom Fields WordPress plugin (free or PRO).

Overview

Display a select list of all countries in your language.

Country names are available in every language (see available list, generated from Unicode CLDR via symfony/intl). By default, country names are localized in your current WordPress language.

Select a single value:

Or multiple ones:

Requirements

WordPress 6.0+
PHP 8.2+
ACF 6.0+ (free or PRO)

Field options

Option	Default	Description
Default value	empty	Default country, as a country code (e.g. `FR`)
Allow null	`false`	Allow an empty value
Select multiple values	`false`	Allow selecting several countries
Stylized UI	`false`	Use an enhanced select field (Select2)
Return format	`array`	See below

Return formats

Values are stored as ISO 3166-1 alpha-2 codes. get_field() returns, for France:

Return format	Value
Country code and name (`array`)	`['value' => 'FR', 'label' => 'France']`
Country code (`value`)	`'FR'`
Country name (`name`)	`'France'`
Country emoji flag (`emoji`)	`'🇫🇷'`

With multiple values, you get an array of those. Country names use the site language.

Since codes are stored, you can query posts by country:

$events = new WP_Query([
    'post_type' => 'event',
    'meta_query' => [['key' => 'country', 'value' => 'FR']],
]);

For a multiple field, values are serialized: compare with 'LIKE' and '"FR"'.

Public functions

use function n5s\AcfCountry\get_countries;
use function n5s\AcfCountry\get_country_flag;
use function n5s\AcfCountry\get_country_name;

get_countries();             // ['AF' => 'Afghanistan', ...], in the site language
get_countries('fr_FR');      // [..., 'ZA' => 'Afrique du Sud', ...]
get_country_name('DE');      // 'Germany', null for an unknown code
get_country_flag('FR');      // '🇫🇷', '' when the code is not two letters

Classes and methods marked @internal are not part of the public API and may change in minor versions.

Filters

You can remove (or add) some countries with the acf/country/countries filter, example:

add_filter('acf/country/countries', static function (array $countries): array {
    unset($countries['IC'], $countries['EA']);

    return $countries;
});

The filter also receives the locale of the list as a second argument. Admin screens use the language of the logged-in user, while values returned by get_field() use the site language.

Integrations

REST API: the field schema lists the country codes, and invalid codes are rejected.
Admin Columns 7+ (free or Pro): custom field columns show flags and country names.
WPGraphQL for ACF 2+: country fields are exposed as an AcfCountry object (code, name, emoji), or a list of them for multiple fields.

Installation

Zip

Download acf-country.zip from the latest release and extract it to your plugins folder. The "Source code" archives GitHub adds to each release are not installable: they lack the autoloader.

Composer

composer require hellonico/acf-country

Composer installs use your project's autoloader: the site must load Composer's vendor/autoload.php, as Bedrock does. Without an autoloader, the plugin shows an admin notice and stays inactive.

Upgrading

From 3.x, see UPGRADE-4.0.

Contributing

See CONTRIBUTING.

Support

This ACF field was originally developed for a personal project I don't use anymore. I still decided to maintain it anyway. If you use it in a commercial project, please consider supporting it on Open Collective.

hellonico / acf-country

Package info

Security

Fund package maintenance!

Statistics