pennants

Core API. import { loadPennant, getPennantName } from 'pennants'.

Interfaces

FetchPennantOptions

Options of fetchPennant.

Properties

Property	Type	Description
base?	string	Base URL where the package's svg/ folder is served (see pennantUrl). Defaults to the version-pinned jsDelivr CDN.
shape?	"pennant" | "rect" | "square" | "circle"	Flag shape, pennant by default: fetches <base>/svg/<shape>/<code>.svg.

---

FlagArt

Flag artwork, as exported by the pennants/art/<set>/<code> modules.

Properties

Property	Type	Description
code	string	Lowercase flag code, e.g. ar or gb-eng. Its ids use the pn-<code>- prefix.
content	string	Inner markup of the source drawing (everything inside its root <svg>).
viewBox	string	viewBox of the source drawing.

---

FlagOptions

Options of loadFlag and renderFlag.

Properties

Property	Type	Description
idPrefix?	string	Replaces the pn-<code>- id namespace of the frame and artwork, e.g. to inline the same flag several times in one document. Must match /^[A-Za-z][\w-]*$/.
shape?	"pennant" | "rect" | "square" | "circle"	Flag shape, pennant by default.

---

LoadArtOptions

Options of loadArt.

Properties

Property	Type	Description
set?	ArtSet	Artwork set: 1x1 (default; pennant, square, circle) or 4x3 (rect).

---

PennantUrlOptions

Options of pennantUrl.

Properties

Property	Type	Description
base?	string	Base URL where the package's svg/ (or png/) folder is served.
format?	"svg" | "png"	Asset format: svg (default, <base>/svg/<shape>/<code>.svg) or png (<base>/png/<shape>/<scale>x/<code>.png).
scale?	2 | 1	PNG density folder, only used when format is png. 2 exists for the pennant shape only; other shapes ship 1x PNGs (use SVG for crisp output).
shape?	"pennant" | "rect" | "square" | "circle"	Flag shape, pennant by default. Selects the <shape>/ folder.

---

ShapeSize

Size in CSS pixels.

Properties

Property	Type	Description
height	number	Height in CSS pixels.
width	number	Width in CSS pixels.

Type Aliases

ArtSet

type ArtSet = "1x1" | "4x3";

Source artwork set: flag-icons' square (1x1) or 4:3 (4x3) drawings.

---

PennantCode

type PennantCode = typeof codes[number];

A flag code accepted by every pennants API, e.g. 'ar' or 'gb-eng'.

---

PennantShape

type PennantShape = typeof SHAPES[number];

A flag shape: 'pennant' (default), 'rect' (4:3), 'square' or 'circle'.

Variables

codes

const codes: readonly PennantCode[];

Every available flag code, sorted: ISO 3166-1 alpha-2 countries plus regions and organisations (e.g. gb-eng, es-ct, eu, un).

---

DEFAULT_CDN_BASE

const DEFAULT_CDN_BASE: string;

Default base of pennantUrl and fetchPennant: the jsDelivr CDN pinned to this package version, e.g. https://cdn.jsdelivr.net/npm/pennants@0.1.0.

---

isoCodes

const isoCodes: readonly PennantCode[];

The subset of codes that are ISO 3166-1 alpha-2 countries.

---

PENNANT_ASPECT_RATIO

const PENNANT_ASPECT_RATIO: number;

Width / height ratio of a pennant (66 / 72 ≈ 0.9167), e.g. for CSS aspect-ratio.

---

PENNANT_HEIGHT

const PENNANT_HEIGHT: 72 = 72;

Intrinsic height of every pennant, in CSS pixels (SVG viewBox units).

---

PENNANT_WIDTH

const PENNANT_WIDTH: 66 = 66;

Intrinsic width of every pennant, in CSS pixels (SVG viewBox units).

---

SHAPE_ART

const SHAPE_ART: Readonly<Record<PennantShape, ArtSet>>;

Artwork set each shape is drawn from.

---

SHAPE_SIZE

const SHAPE_SIZE: Readonly<Record<PennantShape, ShapeSize>>;

Intrinsic size in CSS pixels of each shape's SVG.

---

SHAPES

const SHAPES: readonly ["pennant", "rect", "square", "circle"];

Every available shape. pennant is the default and the library's signature.

Functions

fetchPennant()

function fetchPennant(code, options?): Promise<string>;

Fetches the SVG markup of one flag from static assets (<base>/svg/<shape>/<code>.svg) instead of bundling it. Requests are cached and de-duplicated per URL. The response is parsed with DOMParser and must be a single <svg> document made only of allowlisted SVG elements and attributes (no scripts, event handlers, style, external references or HTML); it is then re-serialised. So a misconfigured or hostile base cannot inject markup. Browser-only: without DOMParser (plain Node/SSR) it rejects; render on the server with loadFlag/renderFlag instead. Rejects with a RangeError for unknown codes or shapes.

Parameters

Parameter	Type
code	string
options?	FetchPennantOptions

Returns

Promise<string>

---

getPennantName()

function getPennantName(code, locale?): string;

Localised flag name. ISO 3166-1 names come from Intl.DisplayNames (no bundled data); other flags (gb-eng, asean, ...) use a small bundled English table. Falls back to the uppercase code as a last resort.

Parameters

Parameter	Type	Default value
code	string	undefined
locale?	string	'en'

Returns

string

---

isPennantCode()

function isPennantCode(value): value is PennantCode;

Exact type guard for supported flag codes (lowercase, e.g. ar, gb-eng). Use toPennantCode to normalise user input such as ' AR '.

Parameters

Parameter	Type
value	unknown

Returns

value is PennantCode

---

isShape()

function isShape(value): value is "pennant" | "rect" | "square" | "circle";

true for a valid shape name.

Parameters

Parameter	Type
value	unknown

Returns

value is "pennant" | "rect" | "square" | "circle"

---

loadArt()

function loadArt(code, options?): Promise<FlagArt>;

Loads one flag's artwork ({ code, viewBox, content }). Each flag and set lives in its own chunk, so only what you request is downloaded. Rejects with a RangeError for unknown codes.

Parameters

Parameter	Type
code	string
options?	LoadArtOptions

Returns

Promise<FlagArt>

---

loadFlag()

function loadFlag(code, options?): Promise<string>;

Loads one flag and returns its SVG markup in the requested shape. The artwork set matching the shape is loaded lazily (one chunk per flag). Rejects with a RangeError for unknown codes or shapes.

Parameters

Parameter	Type
code	string
options?	FlagOptions

Returns

Promise<string>

---

loadPennant()

function loadPennant(code): Promise<string>;

Loads one flag as a pennant: alias of loadFlag(code, { shape: 'pennant' }).

Parameters

Parameter	Type
code	string

Returns

Promise<string>

---

pennantUrl()

function pennantUrl(code, options?): string;

Builds the URL of a static flag asset. Defaults to the jsDelivr CDN, pinned to this package version, so it works without bundler configuration. Throws a RangeError for unknown codes, shapes or formats, and for PNG densities that are not shipped (2x exists for pennant only).

Parameters

Parameter	Type
code	string
options?	PennantUrlOptions

Returns

string

---

renderFlag()

function renderFlag(art, options?): string;

Wraps artwork in a shape's frame and returns a standalone SVG string. Synchronous: use it with statically imported art for SSR, e.g. renderFlag(ar, { shape: 'circle' }) with import ar from 'pennants/art/1x1/ar' (rect expects pennants/art/4x3/<code>).

Parameters

Parameter	Type
art	FlagArt
options?	FlagOptions

Returns

string

---

toDataUri()

function toDataUri(svg): string;

Encodes SVG markup as a data: URI usable in <img src> or CSS url().

Parameters

Parameter	Type
svg	string

Returns

string

---

toEmoji()

function toEmoji(code): string;

Converts a code to its emoji flag (handy as a text fallback). Returns an empty string when no emoji exists, e.g. for gb-eng or xx.

Parameters

Parameter	Type
code	string

Returns

string

---

toPennantCode()

function toPennantCode(value): PennantCode;

Normalises user input to a PennantCode, throwing on unknown codes.

Parameters

Parameter	Type
value	string

Returns

PennantCode

---

toShape()

function toShape(value): "pennant" | "rect" | "square" | "circle";

Validates a shape name, throwing a RangeError for anything else.

Parameters

Parameter	Type
value	unknown

Returns

"pennant" | "rect" | "square" | "circle"