react-flaglet

Tree-shakeable React country flag components. Crisp SVG flags for all ISO 3166-1 countries, loaded only when you use them.

• Dynamic <Flag code="US" /> that lazy-loads each flag's SVG on demand.
• Static, tree-shakeable per-flag components (import { FlagUS } from "react-flaglet/flags").
• Full TypeScript autocomplete for every valid country code.
• Accepts alpha-2, alpha-3, and numeric ISO codes.
• Accessibility baked in (role="img" + country-name label).
• Dual ESM / CommonJS builds, react as the only peer dependency.

Live example

Live demo and API reference: https://ssunils.github.io/flag-library/

The source lives in demo/. It can be run locally with Vite, is deployed to GitHub Pages on every push to main, and can also be shared as a single-file example from a GitHub Gist (no build step) via demo/standalone.html. See demo/README.md for all three.

Install

npm install react-flaglet

react >= 16.8 is a peer dependency.

Entry points

| Import | Provides | | --------------------- | -------------------------------------------------------------- | | react-flaglet | Flag, countryCodes, countryNames, resolveCode, types | | react-flaglet/flags | One component per country: FlagAD, FlagAE, ... FlagZW |

Usage

Dynamic (lazy-loaded)

Best when the flag is chosen at runtime (e.g. from API data). Importing Flag does not pull every flag into your bundle; each SVG is a separate chunk loaded on demand.

import { Flag } from "react-flaglet";

<Flag code="US" />
<Flag code="GB" size="l" rounded />
<Flag code="JP" width={48} title="Japan" />
<Flag code="DEU" />          {/* alpha-3 works too */}
<Flag code="250" />          {/* numeric works too */}

Static (fully tree-shakeable)

Best when the set of flags is known at build time. Only the flags you import ship in your bundle.

import { FlagUS, FlagGB } from "react-flaglet/flags";

<FlagUS width={32} />
<FlagGB />

Each component is named Flag + the uppercase ISO alpha-2 code (FlagUS, FlagGB, FlagJP) and accepts standard SVGProps<SVGSVGElement> (width, height, className, style, ...). They default to role="img" with the country name as the label.

<Flag> props

| Prop | Type | Default | Notes | | ----------- | -------------------------- | -------------- | -------------------------------------------------------- | | code | string | required | ISO alpha-2 / alpha-3 / numeric | | size | "s" \| "m" \| "l" | "m" | 16 / 20 / 32 px wide (4:3) | | width | number | from size | Overrides size; height derived from ratio | | height | number | from width | Override height explicitly | | rounded | boolean \| number | false | true for a default radius, or a px value | | title | string | country name | Accessible label; pass "" to mark decorative | | fallback | ReactNode | null | Rendered for unknown codes and while a flag chunk loads | | ...rest | SVGProps<SVGSVGElement> | | className, style, event handlers, etc. |

Utilities

import { countryCodes, countryNames, resolveCode } from "react-flaglet";

countryCodes;            // ["AD", "AE", ...] all known alpha-2 codes
countryNames.US;         // "United States of America"
resolveCode("usa");      // "US"  (normalizes alpha-2/alpha-3/numeric)
resolveCode("nope");     // undefined

TypeScript

react-flaglet ships its own types. The code prop accepts a FlagInput, which gives autocomplete for every known code while still tolerating an arbitrary string at runtime (handy for codes coming from an API).

import type { CountryCode, Alpha3Code, FlagInput, FlagComponent } from "react-flaglet";

const code: CountryCode = "US"; // autocompleted union of all alpha-2 codes

Server-side rendering

The static components (react-flaglet/flags) render synchronously and work in any SSR or React Server Components setup. The dynamic <Flag> uses React.lazy + Suspense, so wrap it in a <Suspense> boundary (or rely on the built-in one) and provide a fallback if you need a placeholder during hydration. When the flag set is known ahead of time, prefer the static components for SSR.

Accessibility

Each flag renders with role="img" and an aria-label set to the country name. For decorative flags next to a visible country name, pass title="" to hide it from assistive technology.

Flag artwork and naming

Flag SVGs are generated from flagpack (MIT). Country codes and names mirror that dataset. Flags can be politically sensitive; react-flaglet does not take a position on contested territories and simply reflects the upstream dataset. Corrections to flag artwork or codes are best filed upstream with flagpack.

See THIRD_PARTY_LICENSES for attribution.

License

MIT