manifest / utilities / easy-country-flags

Easy Country Flags

A WordPress plugin to display country flags using a shortcode.

by CauseLabs · github.com/causelabs/easy-country-flags · website

★ 2stars

Install

Download source zip No release zip yet

This is the repository archive. It installs, but the folder name will carry the branch suffix and updates will not flow.

Install straight from GitHub with WP-CLI:

wp plugin install https://github.com/causelabs/easy-country-flags/archive/refs/heads/master.zip

No built-in updater. New versions won't appear under Dashboard → Updates. Install new releases yourself, or let Git Updater track the repository.

Readme github.com/causelabs/easy-country-flags ↗

A purpose-built and bloat free plugin to display country flags via the [ecf_flag] shortcode.

Easy Country Flags provides a single shortcode to display country flags (ISO 3166-1 alpha-2 codes) as SVG images. Flags are sourced from the flag-icons npm package (4x3 and 1x1) and shipped with the plugin for performance and offline use. Square icons use native 1:1 assets.

No settings page
No external SDKs or tracking
Shortcode: [ecf_flag]

Requirements

WordPress 5.9+
PHP 7.4+

Installation

Upload the easy-country-flags folder to wp-content/plugins/, or install via WordPress admin → Plugins → Add New (if distributed).
Activate Easy Country Flags in the Plugins screen.

Usage

[ecf_flag flag="US"]
[ecf_flag flag="GB" size="2em"]
[ecf_flag flag="DE" size="24" class="my-flag" title="Germany"]
[ecf_flag flag="FR" square="true"]

Attributes

Attribute	Required	Description
`flag`	Yes	Two-letter ISO country code (e.g. US, GB, DE).
`size`	No	CSS dimension (default: 1em). Examples: 24, 24px, 2em, 1.5rem.
`class`	No	Extra CSS class(es) for the img element.
`title`	No	Used as the image alt text (accessible name).
`square`	No	true/false. When true, the native 1x1 (square) flag asset is used.

Invalid or unsupported flag values output nothing (no broken image).

Custom flags

Use the ecf_flag_url filter to supply image URLs for codes not in the plugin (e.g. international or regional). Your URL is used in the same markup as built-in flags.

Filter parameters: $url (default URL or empty), $code (flag code, lowercase), $square (whether 1x1 was requested). Return the full image URL, or the original $url to keep the default.

Example (theme functions.php or plugin):

add_filter( 'ecf_flag_url', function ( $url, $code, $square ) {
    if ( $code === 'international' ) {
        $base = get_stylesheet_directory_uri() . '/assets/images/';
        return $base . ( $square ? 'international-square.svg' : 'international.svg' );
    }
    return $url;
}, 10, 3 );

Then use [ecf_flag flag="international"] in content.

Development

To update flags from flag-icons: run npm install then npm run copy-flags in the plugin directory.

This copies 4x3 and 1x1 SVGs from node_modules/flag-icons/flags/ into assets/flags/4x3/ and assets/flags/1x1/, and regenerates assets/valid-codes.json (codes available in both aspect ratios).