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

★ 1stars

0forks

Install

No release zip yet. The repository archive installs, but the folder name will carry the branch suffix and updates will not flow:

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

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).