WPGO documentationSVG Flags

Generated product reference

Every SVG Flags control, in one place.

Use this technical reference when you know the block or shortcode you need. It is generated from the same public contracts used by SVG Flags 0.9.7.

Current documentation Version 0.9.7Released 10 August 2026See what changed

Blocks4

Editor controls and saved block attributes.

Shortcodes4

Established shortcode attributes and aliases.

Developer filters21

Public extension points verified in the released source.

Block editor

Block settings

The saved attribute name is shown below each human label. Pro rows appear only when the Pro edition provides that control.

Block · 13 settings

SVG Flag

Free

Render a CSS-backed flag symbol as an inline or block-level element.

SVG Flag settings
Setting	Edition	Type and default	Purpose and accepted values
Flag`flag`	Free	stringDefault: `{"value":"GB","label":"United Kingdom"}`	Choose a code from the bundled 271-entry flag catalogue. Blocks store the selected code and label as JSON; shortcodes accept the code directly. Two-letter country or supported regional/organisation code Block example: {"value":"GB","label":"United Kingdom"} Shortcode example: gb
Flag size`size`	Free	stringDefault: `5`	Set the flag width or maximum grid-item width before the selected CSS unit is appended. Non-negative numeric value The legacy shortcode width attribute is also accepted by the single-flag, image, and heading renderers
Size unit`size_unit`	Free	stringDefault: `em`	Choose the CSS unit appended to size. px em rem vw vh Grid also offers %
Square aspect ratio`square`	Free	booleanDefault: `false`	Use the bundled 1:1 artwork instead of the default 4:3 artwork. true false
Country-name caption`caption`	Free	booleanDefault: `false`	Show the catalogue name below a non-inline flag or each grid image. true false Single inline flags suppress captions
Inline display`inline`	Free	booleanDefault: `false`	Render a single flag inline rather than as a block-level element. true false
Inline vertical alignment`inline_valign`	Free	stringDefault: `middle`	Align an inline flag relative to surrounding text. baseline bottom middle sub super text-bottom text-top top
Random flag`random`	Free	booleanDefault: `false`	Choose one supported flag for each server-side render instead of using flag. true false
Element ID`id`	Pro	stringDefault: `Empty`	Add an HTML id to the rendered single-flag element. A valid HTML id Empty for no id
Custom CSS class`flag_class`	Pro	stringDefault: `Empty`	Append a custom CSS class to the rendered flag element. A CSS class token Empty for no additional class
Country tooltip`tooltip`	Pro	booleanDefault: `false`	Add a title tooltip containing the catalogue country name or custom_tooltip. true false
Custom tooltip`custom_tooltip`	Pro	stringDefault: `Empty`	Replace the catalogue name used by an enabled tooltip. Plain text Empty to use the catalogue name
Custom caption`custom_caption`	Pro	stringDefault: `Empty`	Replace the catalogue country name shown by an enabled caption. Plain text Empty to use the catalogue name

Block · 17 settings

SVG Flag Image

Free

Render an accessible, lazy-loaded SVG image with optional caption and Pro presentation controls.

SVG Flag Image settings
Setting	Edition	Type and default	Purpose and accepted values
Flag`flag`	Free	stringDefault: `{"value":"GB","label":"United Kingdom"}`	Choose a code from the bundled 271-entry flag catalogue. Blocks store the selected code and label as JSON; shortcodes accept the code directly. Two-letter country or supported regional/organisation code Block example: {"value":"GB","label":"United Kingdom"} Shortcode example: gb
Flag size`size`	Free	stringDefault: `5`	Set the flag width or maximum grid-item width before the selected CSS unit is appended. Non-negative numeric value The legacy shortcode width attribute is also accepted by the single-flag, image, and heading renderers
Size unit`size_unit`	Free	stringDefault: `em`	Choose the CSS unit appended to size. px em rem vw vh Grid also offers %
Square aspect ratio`square`	Free	booleanDefault: `false`	Use the bundled 1:1 artwork instead of the default 4:3 artwork. true false
Country-name caption`caption`	Free	booleanDefault: `false`	Show the catalogue name below a non-inline flag or each grid image. true false Single inline flags suppress captions
Inline display`inline`	Free	booleanDefault: `false`	Render a single flag inline rather than as a block-level element. true false
Inline vertical alignment`inline_valign`	Free	stringDefault: `middle`	Align an inline flag relative to surrounding text. baseline bottom middle sub super text-bottom text-top top
Random flag`random`	Free	booleanDefault: `false`	Choose one supported flag for each server-side render instead of using flag. true false
Element ID`id`	Pro	stringDefault: `Empty`	Add an HTML id to the rendered single-flag element. A valid HTML id Empty for no id
Custom CSS class`flag_class`	Pro	stringDefault: `Empty`	Append a custom CSS class to the rendered flag element. A CSS class token Empty for no additional class
Country tooltip`tooltip`	Pro	booleanDefault: `false`	Add a title tooltip containing the catalogue country name or custom_tooltip. true false
Custom tooltip`custom_tooltip`	Pro	stringDefault: `Empty`	Replace the catalogue name used by an enabled tooltip. Plain text Empty to use the catalogue name
Custom caption`custom_caption`	Pro	stringDefault: `Empty`	Replace the catalogue country name shown by an enabled caption. Plain text Empty to use the catalogue name
Image border`border`	Pro	stringDefault: `Empty`	Apply a CSS border to an SVG Flag Image. Valid CSS border shorthand Empty for no custom border
Image border radius`border_radius`	Pro	stringDefault: `Empty`	Apply a CSS border radius to an SVG Flag Image. Valid CSS border-radius value Empty for no custom radius
Image padding`padding`	Pro	stringDefault: `Empty`	Apply CSS padding to an SVG Flag Image. Valid CSS padding value Empty for no custom padding
Image margin`margin`	Pro	stringDefault: `Empty`	Apply CSS margin to an SVG Flag Image. Valid CSS margin value Empty for no custom margin

Block · 8 settings

SVG Flag Grid

Free

Render up to 100 unique valid flags in a responsive grid with optional country-name captions.

SVG Flag Grid settings
Setting	Edition	Type and default	Purpose and accepted values
Flags`flags`	Free	arrayDefault: `["GB","US","CA","FR","DE","JP"]`	Choose the ordered flags rendered by the grid. Block: array of supported uppercase codes Shortcode: comma- or whitespace-separated codes Duplicate and invalid codes are removed; at most 100 are rendered
Grid columns`columns`	Free	numberDefault: `3`	Set the responsive grid column count. Integer from 1 to 8
Grid gap`gap`	Free	stringDefault: `1`	Set the distance between grid items before gap_unit is appended. Non-negative numeric value
Gap unit`gap_unit`	Free	stringDefault: `rem`	Choose the CSS unit appended to gap. px em rem % vw
Flag size`size`	Free	stringDefault: `8`	Set the flag width or maximum grid-item width before the selected CSS unit is appended. Non-negative numeric value The legacy shortcode width attribute is also accepted by the single-flag, image, and heading renderers
Size unit`size_unit`	Free	stringDefault: `rem`	Choose the CSS unit appended to size. px em rem vw vh Grid also offers %
Square aspect ratio`square`	Free	booleanDefault: `false`	Use the bundled 1:1 artwork instead of the default 4:3 artwork. true false
Country-name caption`caption`	Free	booleanDefault: `true`	Show the catalogue name below a non-inline flag or each grid image. true false Single inline flags suppress captions

Block · 19 settings

SVG Flag Heading

Pro

Render a semantic heading containing a decorative flag followed by plain heading text.

SVG Flag Heading settings
Setting	Edition	Type and default	Purpose and accepted values
Flag`flag`	Pro	stringDefault: `{"value":"GB","label":"United Kingdom"}`	Choose a code from the bundled 271-entry flag catalogue. Blocks store the selected code and label as JSON; shortcodes accept the code directly. Two-letter country or supported regional/organisation code Block example: {"value":"GB","label":"United Kingdom"} Shortcode example: gb
Flag size`size`	Pro	stringDefault: `1`	Set the flag width or maximum grid-item width before the selected CSS unit is appended. Non-negative numeric value The legacy shortcode width attribute is also accepted by the single-flag, image, and heading renderers
Size unit`size_unit`	Pro	stringDefault: `em`	Choose the CSS unit appended to size. px em rem vw vh Grid also offers %
Square aspect ratio`square`	Pro	booleanDefault: `false`	Use the bundled 1:1 artwork instead of the default 4:3 artwork. true false
Country-name caption`caption`	Pro	booleanDefault: `false`	Show the catalogue name below a non-inline flag or each grid image. This saved compatibility attribute is registered by the 0.9.7 heading block but is not consumed by its current renderer. true false Single inline flags suppress captions
Inline display`inline`	Pro	booleanDefault: `true`	Render a single flag inline rather than as a block-level element. This saved compatibility attribute is registered by the 0.9.7 heading block but is not consumed by its current renderer. true false
Inline vertical alignment`inline_valign`	Pro	stringDefault: `baseline`	Align an inline flag relative to surrounding text. baseline bottom middle sub super text-bottom text-top top
Random flag`random`	Pro	booleanDefault: `false`	Choose one supported flag for each server-side render instead of using flag. true false
Element ID`id`	Pro	stringDefault: `Empty`	Add an HTML id to the rendered single-flag element. This saved compatibility attribute is registered by the 0.9.7 heading block but is not consumed by its current renderer. A valid HTML id Empty for no id
Custom CSS class`flag_class`	Pro	stringDefault: `Empty`	Append a custom CSS class to the rendered flag element. This saved compatibility attribute is registered by the 0.9.7 heading block but is not consumed by its current renderer. A CSS class token Empty for no additional class
Country tooltip`tooltip`	Pro	booleanDefault: `false`	Add a title tooltip containing the catalogue country name or custom_tooltip. This saved compatibility attribute is registered by the 0.9.7 heading block but is not consumed by its current renderer. true false
Custom tooltip`custom_tooltip`	Pro	stringDefault: `Empty`	Replace the catalogue name used by an enabled tooltip. This saved compatibility attribute is registered by the 0.9.7 heading block but is not consumed by its current renderer. Plain text Empty to use the catalogue name
Custom caption`custom_caption`	Pro	stringDefault: `Empty`	Replace the catalogue country name shown by an enabled caption. This saved compatibility attribute is registered by the 0.9.7 heading block but is not consumed by its current renderer. Plain text Empty to use the catalogue name
Image border`border`	Pro	stringDefault: `Empty`	Apply a CSS border to an SVG Flag Image. This saved compatibility attribute is registered by the 0.9.7 heading block but is not consumed by its current renderer. Valid CSS border shorthand Empty for no custom border
Image border radius`border_radius`	Pro	stringDefault: `Empty`	Apply a CSS border radius to an SVG Flag Image. This saved compatibility attribute is registered by the 0.9.7 heading block but is not consumed by its current renderer. Valid CSS border-radius value Empty for no custom radius
Image padding`padding`	Pro	stringDefault: `Empty`	Apply CSS padding to an SVG Flag Image. This saved compatibility attribute is registered by the 0.9.7 heading block but is not consumed by its current renderer. Valid CSS padding value Empty for no custom padding
Image margin`margin`	Pro	stringDefault: `Empty`	Apply CSS margin to an SVG Flag Image. This saved compatibility attribute is registered by the 0.9.7 heading block but is not consumed by its current renderer. Valid CSS margin value Empty for no custom margin
Heading level`heading_tag`	Pro	stringDefault: `h2`	Choose the semantic HTML heading element that wraps the Pro flag heading. h1 h2 h3 h4 h5 h6
Heading text`heading`	Pro	stringDefault: `Empty`	Set the plain-text content displayed after the decorative flag in a Pro heading. Plain text Empty while editing displays a temporary prompt only

Established workflows

Shortcode attributes

Shortcodes remain supported for existing content and code-led builds. Add only attributes whose defaults you need to change.

Shortcode · 13 attributes

[svg-flag]

Free

Render one CSS-backed flag. The svg-flags alias remains supported for established content.

Aliases: [svg-flags]

[svg-flag]

[svg-flag] attributes
Attribute	Edition	Type and default	Purpose and accepted values
Flag`flag`	Free	stringDefault: `{"value":"GB","label":"United Kingdom"}`	Choose a code from the bundled 271-entry flag catalogue. Blocks store the selected code and label as JSON; shortcodes accept the code directly. Two-letter country or supported regional/organisation code Block example: {"value":"GB","label":"United Kingdom"} Shortcode example: gb
Flag size`size`	Free	stringDefault: `5`	Set the flag width or maximum grid-item width before the selected CSS unit is appended. Non-negative numeric value The legacy shortcode width attribute is also accepted by the single-flag, image, and heading renderers
Size unit`size_unit`	Free	stringDefault: `em`	Choose the CSS unit appended to size. px em rem vw vh Grid also offers %
Square aspect ratio`square`	Free	booleanDefault: `false`	Use the bundled 1:1 artwork instead of the default 4:3 artwork. true false
Country-name caption`caption`	Free	booleanDefault: `false`	Show the catalogue name below a non-inline flag or each grid image. true false Single inline flags suppress captions
Inline display`inline`	Free	booleanDefault: `false`	Render a single flag inline rather than as a block-level element. true false
Inline vertical alignment`inline_valign`	Free	stringDefault: `middle`	Align an inline flag relative to surrounding text. baseline bottom middle sub super text-bottom text-top top
Random flag`random`	Free	booleanDefault: `false`	Choose one supported flag for each server-side render instead of using flag. true false
Element ID`id`	Pro	stringDefault: `Empty`	Add an HTML id to the rendered single-flag element. A valid HTML id Empty for no id
Custom CSS class`flag_class`	Pro	stringDefault: `Empty`	Append a custom CSS class to the rendered flag element. A CSS class token Empty for no additional class
Country tooltip`tooltip`	Pro	booleanDefault: `false`	Add a title tooltip containing the catalogue country name or custom_tooltip. true false
Custom tooltip`custom_tooltip`	Pro	stringDefault: `Empty`	Replace the catalogue name used by an enabled tooltip. Plain text Empty to use the catalogue name
Custom caption`custom_caption`	Pro	stringDefault: `Empty`	Replace the catalogue country name shown by an enabled caption. Plain text Empty to use the catalogue name

Shortcode · 17 attributes

[svg-flag-image]

Free

Render one lazy-loaded SVG image with meaningful alternative text.

[svg-flag-image]

[svg-flag-image] attributes
Attribute	Edition	Type and default	Purpose and accepted values
Flag`flag`	Free	stringDefault: `{"value":"GB","label":"United Kingdom"}`	Choose a code from the bundled 271-entry flag catalogue. Blocks store the selected code and label as JSON; shortcodes accept the code directly. Two-letter country or supported regional/organisation code Block example: {"value":"GB","label":"United Kingdom"} Shortcode example: gb
Flag size`size`	Free	stringDefault: `5`	Set the flag width or maximum grid-item width before the selected CSS unit is appended. Non-negative numeric value The legacy shortcode width attribute is also accepted by the single-flag, image, and heading renderers
Size unit`size_unit`	Free	stringDefault: `em`	Choose the CSS unit appended to size. px em rem vw vh Grid also offers %
Square aspect ratio`square`	Free	booleanDefault: `false`	Use the bundled 1:1 artwork instead of the default 4:3 artwork. true false
Country-name caption`caption`	Free	booleanDefault: `false`	Show the catalogue name below a non-inline flag or each grid image. true false Single inline flags suppress captions
Random flag`random`	Free	booleanDefault: `false`	Choose one supported flag for each server-side render instead of using flag. true false
Inline display`inline`	Free	booleanDefault: `false`	Render a single flag inline rather than as a block-level element. true false
Inline vertical alignment`inline_valign`	Free	stringDefault: `middle`	Align an inline flag relative to surrounding text. baseline bottom middle sub super text-bottom text-top top
Element ID`id`	Pro	stringDefault: `Empty`	Add an HTML id to the rendered single-flag element. A valid HTML id Empty for no id
Custom CSS class`flag_class`	Pro	stringDefault: `Empty`	Append a custom CSS class to the rendered flag element. A CSS class token Empty for no additional class
Country tooltip`tooltip`	Pro	booleanDefault: `false`	Add a title tooltip containing the catalogue country name or custom_tooltip. true false
Custom tooltip`custom_tooltip`	Pro	stringDefault: `Empty`	Replace the catalogue name used by an enabled tooltip. Plain text Empty to use the catalogue name
Custom caption`custom_caption`	Pro	stringDefault: `Empty`	Replace the catalogue country name shown by an enabled caption. Plain text Empty to use the catalogue name
Image border`border`	Pro	stringDefault: `Empty`	Apply a CSS border to an SVG Flag Image. Valid CSS border shorthand Empty for no custom border
Image border radius`border_radius`	Pro	stringDefault: `Empty`	Apply a CSS border radius to an SVG Flag Image. Valid CSS border-radius value Empty for no custom radius
Image padding`padding`	Pro	stringDefault: `Empty`	Apply CSS padding to an SVG Flag Image. Valid CSS padding value Empty for no custom padding
Image margin`margin`	Pro	stringDefault: `Empty`	Apply CSS margin to an SVG Flag Image. Valid CSS margin value Empty for no custom margin

Shortcode · 8 attributes

[svg-flag-grid]

Free

Render a validated, deduplicated grid of up to 100 flags.

[svg-flag-grid]

[svg-flag-grid] attributes
Attribute	Edition	Type and default	Purpose and accepted values
Flags`flags`	Free	arrayDefault: `["GB","US","CA","FR","DE","JP"]`	Choose the ordered flags rendered by the grid. Block: array of supported uppercase codes Shortcode: comma- or whitespace-separated codes Duplicate and invalid codes are removed; at most 100 are rendered
Grid columns`columns`	Free	numberDefault: `3`	Set the responsive grid column count. Integer from 1 to 8
Grid gap`gap`	Free	stringDefault: `1`	Set the distance between grid items before gap_unit is appended. Non-negative numeric value
Gap unit`gap_unit`	Free	stringDefault: `rem`	Choose the CSS unit appended to gap. px em rem % vw
Flag size`size`	Free	stringDefault: `8`	Set the flag width or maximum grid-item width before the selected CSS unit is appended. Non-negative numeric value The legacy shortcode width attribute is also accepted by the single-flag, image, and heading renderers
Size unit`size_unit`	Free	stringDefault: `rem`	Choose the CSS unit appended to size. px em rem vw vh Grid also offers %
Square aspect ratio`square`	Free	booleanDefault: `false`	Use the bundled 1:1 artwork instead of the default 4:3 artwork. true false
Country-name caption`caption`	Free	booleanDefault: `true`	Show the catalogue name below a non-inline flag or each grid image. true false Single inline flags suppress captions

Shortcode · 8 attributes

[svg-flag-heading]

Pro

Render a semantic heading with a decorative flag image.

[svg-flag-heading]

[svg-flag-heading] attributes
Attribute	Edition	Type and default	Purpose and accepted values
Flag`flag`	Pro	stringDefault: `{"value":"GB","label":"United Kingdom"}`	Choose a code from the bundled 271-entry flag catalogue. Blocks store the selected code and label as JSON; shortcodes accept the code directly. Two-letter country or supported regional/organisation code Block example: {"value":"GB","label":"United Kingdom"} Shortcode example: gb
Flag size`size`	Pro	stringDefault: `1`	Set the flag width or maximum grid-item width before the selected CSS unit is appended. Non-negative numeric value The legacy shortcode width attribute is also accepted by the single-flag, image, and heading renderers
Size unit`size_unit`	Pro	stringDefault: `em`	Choose the CSS unit appended to size. px em rem vw vh Grid also offers %
Square aspect ratio`square`	Pro	booleanDefault: `false`	Use the bundled 1:1 artwork instead of the default 4:3 artwork. true false
Inline vertical alignment`inline_valign`	Pro	stringDefault: `middle`	Align an inline flag relative to surrounding text. baseline bottom middle sub super text-bottom text-top top
Random flag`random`	Pro	booleanDefault: `false`	Choose one supported flag for each server-side render instead of using flag. true false
Heading text`heading`	Pro	stringDefault: `Empty`	Set the plain-text content displayed after the decorative flag in a Pro heading. Plain text Empty while editing displays a temporary prompt only
Heading level`heading_tag`	Pro	stringDefault: `h2`	Choose the semantic HTML heading element that wraps the Pro flag heading. h1 h2 h3 h4 h5 h6

Developer API

Developer filters

These WordPress filters are public extension points. Return the same value type described for each filter.

svg_flag_shortcode_custom_flagFree

Filter the requested CSS-backed flag code before validation.

Value: string
Parameters: $flag — requested code; $atts — resolved attributes
Return: A supported flag code

svg_flag_shortcode_tagFree

Filter the CSS-backed flag wrapper element.

Value: string
Parameters: $tag — div or span; $atts — resolved attributes
Return: div or span; other values are replaced with div

svg_flag_shortcode_idFree

Filter the CSS-backed flag id attribute; Pro uses this to apply id.

Value: string
Parameters: $id — empty by default; $atts — resolved attributes
Return: Sanitised id attribute or empty string

svg_flag_shortcode_flag_classFree

Filter the base CSS classes for a CSS-backed flag.

Value: string
Parameters: $classes — generated class string; $flag — normalized code; $atts — resolved attributes
Return: CSS class string

svg_flag_caption_textFree

Filter a CSS-backed flag caption; Pro uses this for custom captions.

Value: string
Parameters: $text — catalogue name; $atts — resolved attributes
Return: Caption text

svg_flag_shortcode_class_attributeFree

Filter the CSS-backed flag class list; Pro appends flag_class here.

Value: array
Parameters: $classes — class list; $atts — resolved attributes
Return: Class list

svg_flag_shortcode_style_attributeFree

Filter inline CSS declarations for a CSS-backed flag.

Value: array
Parameters: $styles — style list; $atts — resolved attributes
Return: Style declaration list

svg_flag_shortcode_title_attributeFree

Filter the CSS-backed flag title tooltip; Pro supplies tooltip behaviour here.

Value: string
Parameters: $title — empty by default; $atts — resolved attributes; $flag — normalized code
Return: Tooltip text or empty string

svg_flag_image_shortcode_custom_flagFree

Filter the requested image flag code before validation.

Value: string
Parameters: $flag — requested code; $atts — resolved attributes
Return: A supported flag code

svg_flag_image_shortcode_inline_styleFree

Filter the image display declaration.

Value: string
Parameters: $style — display declaration; $atts — resolved attributes
Return: CSS declaration string

svg_flag_image_shortcode_idFree

Filter the image id attribute; Pro uses this to apply id.

Value: string
Parameters: $id — empty by default; $atts — resolved attributes
Return: Sanitised id attribute or empty string

svg_flag_image_caption_textFree

Filter an image caption; Pro uses this for custom captions.

Value: string
Parameters: $text — catalogue name; $atts — resolved attributes
Return: Caption text

svg_flag_image_shortcode_class_attributeFree

Filter image classes; Pro appends flag_class here.

Value: array
Parameters: $classes — class list; $atts — resolved attributes
Return: Class list

svg_flag_image_shortcode_style_attributeFree

Filter image CSS declarations; Pro appends border and spacing here.

Value: array
Parameters: $styles — style list; $atts — resolved attributes
Return: Style declaration list

svg_flag_image_shortcode_title_attributeFree

Filter the image title tooltip; Pro supplies tooltip behaviour here.

Value: string
Parameters: $title — empty by default; $atts — resolved attributes; $flag — normalized code; $countries — catalogue map
Return: Tooltip text or empty string

svg_flag_grid_flagsFree

Filter the normalized grid flag codes before a second validation pass.

Value: array
Parameters: $flags — normalized code list; $atts — resolved attributes
Return: Flag-code array; invalid values are removed

svg_flag_grid_item_htmlFree

Filter each complete grid figure element.

Value: string
Parameters: $html — figure markup; $code — normalized code; $name — catalogue name; $atts — resolved attributes
Return: Grid item HTML

svg_flag_heading_shortcode_custom_flagPro

Filter the requested Pro heading flag code before validation.

Value: string
Parameters: $flag — requested code; $atts — resolved attributes
Return: A supported flag code

svg_flag_heading_shortcode_style_attributePro

Filter CSS declarations applied to the decorative heading image.

Value: array
Parameters: $styles — style list; $atts — resolved attributes
Return: Style declaration list

svg_flag_heading_shortcode_title_attributePro

Filter the decorative heading image title attribute.

Value: string
Parameters: $title — empty by default; $atts — resolved attributes; $flag — normalized code; $countries — catalogue map
Return: Tooltip text or empty string

svg_flag_heading_shortcode_idPro

Filter the Pro heading id attribute.

Value: string
Parameters: $id — empty by default; $atts — resolved attributes
Return: Sanitised id attribute or empty string