SVG Flags Documentation

SVG Flags 0.9.7 documentation. This guide covers the current Free and Pro builds, including all editor blocks, shortcodes, supported flag types, accessibility behaviour, and system requirements.

Release status: version 0.9.7 is in final release preparation. The plugin and its Free/Pro packages are working and documented, but public download and checkout access will open only after final package and purchase-flow verification. See the SVG Flags product page for the current status.

Requirements

• WordPress 6.3 or newer.
• PHP 7.4 or newer.
• Tested with WordPress 7.0.
• A block theme is not required. Blocks, shortcodes, and classic themes are supported.

Plugin installation

When the release packages become publicly available, install either the Free or Pro ZIP file directly from WordPress:

1. Open Plugins → Add Plugin in the WordPress dashboard.
2. Select Upload Plugin, choose the SVG Flags ZIP file, and select Install Now.
3. When installation finishes, select Activate Plugin.
4. If you are using the Free build, you can skip the optional usage-data opt-in. SVG Flags continues to work normally.
5. If you are using Pro, activate the licence when prompted so the site can receive licensed updates and support.

Do not extract the ZIP file before uploading it to WordPress.

Getting started in the block editor

1. Edit a post, page, or another block-enabled content type.
2. Open the block inserter and search for SVG Flag.
3. Choose an SVG Flags block, then use the block settings to search for countries and territories by name or code.
4. Adjust size, ratio, captions, grid layout, or the available Pro controls.
5. Preview and publish the content.

The 271-flag library

SVG Flags 0.9.7 bundles flag-icons 7.5.0 locally. The picker contains 271 current country, territory, regional, and organisation entries. It includes standard country codes plus specialist entries such as:

• ASEAN — Association of Southeast Asian Nations.
• EU — Europe.
• BQ — Bonaire, Sint Eustatius and Saba.
• GB-ENG, GB-SCT, and GB-WLS — England, Scotland, and Wales.
• Regional and organisation flags supplied by the bundled library.

Assets are served from the WordPress site; the front end does not need a hosted flag service or external CDN.

Editor blocks

SVG Flag

Displays one lightweight CSS-backed SVG flag. Use it for compact inline or block-level flags. Controls include the selected flag, size and unit, 4:3 or square ratio, captions, inline display, vertical alignment, and optional random selection.

SVG Flag Image

Displays one flag in an HTML img element. The output uses the country or territory name as alternative text and supports responsive sizing, lazy loading, asynchronous decoding, captions, square or 4:3 assets, and optional random selection.

SVG Flag Grid

Builds a responsive gallery from multiple selected flags. Search and add items by name or code, then remove individual tokens as required.

• Choose from one to eight columns.
• Set the gap and its CSS unit.
• Set a maximum flag width and unit.
• Choose 4:3 or square assets.
• Show or hide country-name captions.
• Add up to 100 valid, unique flags to one grid.

SVG Flag Heading (Pro)

Places a decorative flag beside semantic heading text. Choose an H1–H6 element, flag, size, aspect ratio, and vertical alignment. The flag image is decorative inside the heading so assistive technology reads the heading text once.

Shortcodes

The three core shortcodes work in classic content, templates, and programmatic layouts. Pro also provides the SVG Flag Heading shortcode.

[svg-flag]

Displays one lightweight CSS-backed flag.

[svg-flag flag="gb" size="3" size_unit="em"]

Core attributes: flag, size, size_unit, square, caption, inline, inline_valign, and random.

The legacy [svg-flags] alias still works, but new content should use [svg-flag].

[svg-flag-image]

Displays one semantic SVG image.

[svg-flag-image flag="fr" size="96" size_unit="px" caption="true"]

Core attributes: flag, size, size_unit, square, caption, inline, inline_valign, and random.

[svg-flag-grid]

Displays a responsive collection of unique, validated flag codes.

[svg-flag-grid flags="gb,us,ca,fr,de,jp" columns="3" gap="1" gap_unit="rem" size="8" size_unit="rem" caption="true"]

Attributes:

• flags — comma- or space-separated flag codes.
• columns — a value from 1 to 8.
• gap and gap_unit — spacing between grid items.
• size and size_unit — maximum width for each flag.
• square — set to true for 1:1 assets; otherwise 4:3 assets are used.
• caption — show or hide country names.

[svg-flag-heading] (Pro)

Displays a flag beside semantic heading text.

[svg-flag-heading flag="jp" heading="Japan office" heading_tag="h2" size="1.25" size_unit="em"]

Core attributes: flag, heading, heading_tag, size, size_unit, square, inline_valign, and random.

SVG Flags Pro

Pro keeps the same flag picker and publishing workflow, then adds presentation controls for sites that need exact styling:

• The SVG Flag Heading block and shortcode.
• Custom caption and tooltip text.
• Unique IDs and custom CSS classes.
• Border and border-radius controls.
• Margin and padding controls.
• Additional presentation attributes for supported blocks and shortcodes.

Accessibility and performance

• Flag Image and Flag Grid output includes meaningful country or territory alternative text.
• Decorative images inside Flag Heading output are hidden from assistive technology so the heading is not announced twice.
• Image output uses lazy loading and asynchronous decoding where appropriate.
• SVG assets are bundled locally and require no front-end request to a flag service.
• Captions provide a visible text label when they are useful to the reader.

Troubleshooting

A flag does not appear

Confirm that the selected name or code exists in the picker. Shortcodes ignore unknown codes rather than producing broken image URLs. Clear page and asset caches after updating from an older build.

The editor shows an activation or opt-in screen

Free users can choose Activate Free Version and skip the optional usage-data opt-in. Pro users should enter a valid licence key once public licensing is available.

A grid has fewer items than expected

The grid removes duplicate and unknown codes. A single grid accepts up to 100 valid flags.

Which aspect ratio should I use?

Use the default 4:3 assets for a consistent flag collection. Use square assets when the surrounding design requires equal-width and equal-height tiles.

What changed in version 0.9.7

• Updated the bundled library to flag-icons 7.5.0 with 271 entries.
• Added the responsive SVG Flag Grid block and shortcode.
• Modernised the WordPress block editor integration for current editor APIs.
• Improved accessible image output and safer attribute handling.
• Removed the historical dependency on the separate WPGO plugin framework.
• Added current build, package-boundary, compatibility, and release checks for Free and Pro editions.

Support and product information

Review the SVG Flags product page for release status. If a workflow is unclear or you need to check a planned use before launch, contact WPGO Plugins.