Flags

A flag is an image. The emoji version of it is the thing this component exists to replace: a flag emoji is a pair of regional-indicator code points (U+1F1EA U+1F1F8 for Spain), and Windows has never shipped a glyph for that pair, so it renders as the two bare letters “ES” for most desktop readers. There is no font stack that fixes it, and on the platforms that do draw a flag, each one draws a different one.

read as: the country name, in the reader's language

PropsStyle

Codees, ES, en-GB, gb-eng

Shape

rect 4:3

Height

24px

Labeloverrides the country nameDecorativeno name at allReset

ComponentCSSTailwind

import { Flag } from "@enigmax/primitives/react/flag";

<Flag code="es" size={24} />

Usage

import { Flag } from "@enigmax/primitives/react/flag";

<Flag code="es" />                          // 4:3, 16px tall, named automatically
<Flag code="es" shape="circle" size={20} /> // round, for a chip or an avatar row
<Flag code="es" decorative />               // beside a country name that is already there

import { flagAttributes } from "@enigmax/primitives";

const img = document.createElement("img");
for (const [name, value] of Object.entries(flagAttributes("es", { shape: "circle" }))) {
    img.setAttribute(name, String(value));
}

Installation

The name is automatic

<Flag code="es" /> is announced as Spain - or España on a Spanish page - because the name comes from Intl.DisplayNames, which is already in the runtime, already translated, and maintained by whoever maintains the platform. No table of 250 country names ships with the component, and none of them goes stale.

It lands on alt AND on title, because those do different jobs and only one of them is visible: alt is what a screen reader reads and what shows when the image does not load, while a hover tooltip comes from title and from nothing else.

A name is never invented. A subdivision such as gb-eng is England, and falling back to its region would announce “United Kingdom” - confidently wrong - so it renders as decoration instead. Same for a runtime with no Intl.

The code you pass

code takes what a codebase already holds, which is rarely a tidy ISO code:

The name comes from the runtime’s own region data, so there is no table of 250 names here to go stale, and <Flag code={row.country} /> works against a column that holds “Germany”.

Anything else is null, deliberately. A bare word used to be taken as a file name and rendered as a broken image with no alt text, which is worse than no flag: banana and zz resolve to nothing now, and only a name with a separator (easter_island) is taken on trust, because nothing can check those without shipping the whole directory listing.

A BCP 47 tag is read by its casing, before anything is lowercased: es-ES is a locale and means the flag es, while es-ct is Catalonia and means the file es-ct. Lowercasing first makes those the same string, and then one of them is always wrong.

A code that resolves to nothing renders fallback (nothing, by default). Never a broken image: a 404 with no alt text beside a country name is worse than no flag.

Where the images come from

enigma serves all three sets over a CDN, so nothing has to be installed and no request goes to anyone else:

For a project that will not make a third-party request at runtime - an offline install, a CSP with no img-src for a CDN, a build that must not break the day a CDN does - the same files are downloaded into the project:

It asks which sets, which countries and which formats, and writes public/flags/<shape>/<code>.<format>. Non-interactively it takes every set and every country. Then one line at startup moves the whole app onto those files:

import { configureFlags } from "@enigmax/primitives";

configureFlags({ source: "local", basePath: "/flags" });

source also takes a URL of your own, for a mirror with the same layout.

The artwork is stored as SVG, so that is what a remote source serves. Ask for webp and you get SVG plus one warning in development; png and webp are for a local set, where they are rasterised at download time.

Styling hooks: [data-enigma-flag], plus [data-flag-shape] and [data-flag-code].