matter-flags
Advanced tools
Tree-shakeable, zero-dependency React flag components. 307 flags — 252 countries, 5 organizations, 50 US states + DC. One flag ≈ 2kB gzip. No postinstall, no public/ copying, no CSS import.
<Flag code="ma" /> with circle | rounded | square shapes and pixel or CSS sizes<DuoFlag> fuses two flags: vertical split, diagonal triangles, or overlapping stack<FallbackFlag /> for unknown codes (never crashes), role="img" + labels built inuk → Union Jack, arab, africa)pnpm add matter-flags
# npm install matter-flags | yarn add matter-flags | bun add matter-flags
Requires react ^18 || ^19. Zero runtime dependencies.
// 1. Easiest — code-split <Flag> (only the requested chunk loads)
import { Flag } from 'matter-flags';
<Flag code="ma" shape="circle" size={32} bordered dropShadow gradient="linear" />;
// 2. Smallest — direct import (only MA enters your bundle)
import MA from 'matter-flags/flags/ma';
<MA size={24} shape="circle" />;
// 3. Two flags, one badge
import { DuoFlag } from 'matter-flags';
<DuoFlag a="us" b="gb" layout="split" size={48} shape="circle" bordered />;
<Flag />import { Flag } from 'matter-flags' — client component. Loads the requested flag as a separate chunk (code-split), renders a correct-size placeholder while loading (no layout shift, SSR-safe).
| Prop | Type | Default | Description |
|---|---|---|---|
code | string | — | Case-insensitive code, e.g. "ma", "US", "us-tx", "eu" |
shape | 'circle' | 'rounded' | 'square' | 'rounded' | rounded ≈ 18% radius |
size | number | string | 24 | Number = px, or any CSS size ("2rem", "100%") |
bordered | boolean | true | 1px outline |
borderColor | string | 'rgba(0,0,0,0.15)' | Any CSS color |
borderWidth | number | string | 1 | Number = px |
dropShadow | boolean | false | Soft 0 1px 3px shadow |
gradient | 'none' | 'top-down' | 'linear' | 'circular' | 'none' | Gloss overlay |
title | string | country name | Tooltip + accessible label |
fallback | ReactNode | white flag | Shown while the chunk loads |
className / style | — | — | Passed to the wrapper |
Examples:
// Avatar
<Flag code="jp" shape="circle" size={40} bordered dropShadow />
// Flag + name row
<span style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}>
<Flag code="br" shape="rounded" size={20} />
Brazil
</span>
// Custom border, no border-radius look via square
<Flag code="ch" shape="square" size={28} bordered borderColor="#000" borderWidth={2} />
Every flag is its own module — ideal for lists, tables, and React Server Components (no client JS needed):
import MA from 'matter-flags/flags/ma';
import US from 'matter-flags/flags/us';
import USTX from 'matter-flags/flags/us-tx';
// Named imports also work and tree-shake:
import { MA, US, GB } from 'matter-flags/flags';
Same visual props as <Flag /> minus code/fallback:
// Language picker row (server component)
import FR from 'matter-flags/flags/fr';
<FR size={18} shape="circle" title="Français" />;
<DuoFlag />import { DuoFlag } from 'matter-flags' — two flags in one badge. Same visual props as <Flag />, plus:
| Prop | Type | Default | Description |
|---|---|---|---|
a / b | string | — | Left/top-left/first and right/bottom-right/second codes |
layout | 'split' | 'diagonal' | 'stack' | 'split' | split = left/right halves, diagonal = top-left/bottom-right triangles, stack = overlapping badges |
overlap | number | 35 | Overlap % for stack |
// The classic split circle
<DuoFlag a="us" b="gb" layout="split" size={96} shape="circle" bordered borderColor="#7a4a2b" borderWidth={3} dropShadow />
// Diagonal energies
<DuoFlag a="fr" b="ma" layout="diagonal" size={64} shape="circle" bordered />
// Versus / language-pair badge
<DuoFlag a="en" b="es" layout="stack" size={32} /> // (use real codes: gb/es, fr/ma…)
<FallbackFlag />import { FallbackFlag } from 'matter-flags' — plain white flag in any shape/size. Rendered automatically by <Flag /> and <DuoFlag /> for unknown codes; use directly for skeletons and empty states:
<FallbackFlag size={24} shape="circle" />
Case-insensitive. uk/gb → Union Jack (gb-ukm); British nations (gb-sct, gb-wls, gb-nir) available directly; el → gr.
Organizations (short codes included): eu, un, nato, arab/arab-league, africa/african-union.
US states + DC: us-al … us-wy, us-dc (e.g. us-tx, us-ca, us-oh). No short aliases — al, ca, ar belong to Albania, Canada, Argentina. Mississippi is excluded: its 2020 flag is not public domain.
ad — Andorraae — United Arab Emiratesaf — Afghanistanag — Antigua and Barbudaai — Anguillaal — Albaniaam — Armeniaao — Angolaaq — Antarcticaar — Argentinaas — American Samoaat — Austriaau — Australiaaw — Arubaax — Åland Islandsaz — Azerbaijanba — Bosnia and Herzegovinabb — Barbadosbd — Bangladeshbe — Belgiumbf — Burkina Fasobg — Bulgariabh — Bahrainbi — Burundibj — Beninbl — Saint Barthélemybm — Bermudabn — Bruneibo — Boliviabq-bo — Bonairebq-sa — Sababq-se — Sint Eustatiusbr — Brazilbs — Bahamasbt — Bhutanbv — Bouvet Islandbw — Botswanaby — Belarusbz — Belizeca — Canadacc — Cocos Islandscd — Democratic Republic of Congocf — Central African Republiccg — Congoch — Switzerlandci — Côte d'Ivoireck — Cook Islandcl — Chilecm — Camerooncn — Chinaco — Colombiacr — Costa Ricacu — Cubacv — Cape Verdecw — Curaçaocx — Christmas Islandcy — Cypruscz — Czech Republicde — Germanydj — Djiboutidk — Denmarkdm — Dominicado — Dominican Republicdz — Algeriaec — Ecuadoree — Estoniaeg — Egypter — Eritreaes — Spainet — Ethiopiafi — Finlandfj — Fijifk — Falkland Islandsfm — Micronesia (Federated States of)fo — Faroe Islandfr — Francega — Gabongb-nir — Northern Irelandgb-sct — Scotlandgb-ukm — United Kingdomgb-wls — Walesgd — Grenadage — Georgiagf — French Guianagg — Guernseygh — Ghanagi — Gibraltargl — Greenlandgm — Gambiagn — Guineagp — Guadeloupegq — Equatorial Guineagr — Greecegs — South Georgia and the South Sandwich Islandsgt — Guatemalagu — Guamgw — Guinea-Bissaugy — Guyanahk — Hong Konghm — Heard Island and McDonald Islandshn — Hondurashr — Croatiaht — Haitihu — Hungaryid — Indonesiaie — Irelandim — Isle of Manin — Indiaio — British Indian Ocean Territoryiq — Iraqir — Iranis — Icelandit — Italyje — Jerseyjm — Jamaicajo — Jordanjp — Japanke — Kenyakg — Kyrgyzstankh — Cambodiaki — Kiribatikm — Comoroskn — Saint Kitts and Neviskp — Korea (the Democratic People's Republic of)kr — Korea (the Republic of)kw — Kuwaitky — Cayman Islandskz — Kazakhstanla — Lao People's Democratic Republic (the)lb — Lebanonlc — Saint Luciali — Liechtensteinlk — Sri Lankalr — Liberials — Lesotholt — Lithuanialu — Luxembourglv — Latvialy — Libyama — Moroccomc — Monacomd — Moldova (the Republic of)me — Montenegromf — Saint Martinmg — Madagascarmh — Marshall Islands (the)mk — North Macedoniaml — Malimm — Myanmarmn — Mongoliamo — Macaomp — Northern Mariana Islands (the)mq — Martiniquemr — Mauritaniams — Montserratmt — Maltamu — Mauritiusmv — Maldivesmw — Malawimx — Mexicomy — Malaysiamz — Mozambiquena — Namibianc — New Caledoniane — Nigernf — Norfolk Islandng — Nigeriani — Nicaraguanl — Netherlandsno — Norwaynp — Nepalnr — Naurunu — Niuenz — New Zealandom — Omanpa — Panamape — Perupf — French Polyesiapg — Papua New Guineaph — Philippines (the)pk — Pakistanpl — Polandpm — Saint Pierre and Miquelonpn — Pitcairnpr — Puerto Ricops — Palestine, State ofpt — Portugalpw — Palaupy — Paraguayqa — Qatarre — Réunionro — Romaniars — Serbiaru — Russian Federation (the)rw — Rwandasa — Saudi Arabiasb — Solomon Islandssc — Seychellessd — Sudan (the)se — Swedensg — Singaporesh — Saint Helena, Ascension Island, Traistan da Cunhasi — Sloveniasj — Svalbard, Jan Mayensk — Slovakiasl — Sierra Leonesm — San Marinosn — Senegalso — Somaliasr — Surinamess — South Sudanst — Sao Tome and Principesv — El Salvadorsx — Sint Maartensy — Syrian Arab Republic (the)sz — Eswatinitc — Turks and Caicos Islands (the)td — Chadtf — French Southern Territoriestg — Togoth — Thailandtj — Tajikistantk — Tokelautl — Timor-Lestetm — Turkmenistantn — Tunisiato — Tongatr — Turkeytt — Trinidad and Tobagotv — Tuvalutw — Taiwantz — Tanzania, the United Republic ofua — Ukraineug — Ugandaum — United States Minor Outlying Islands (the)us — United States of Americauy — Uruguayuz — Uzbekistanva — Holy Seevc — Saint Vincent and the Grenadinesve — Venezuela (Bolivarian Republic of)vg — Virgin Islands (British)vi — Virgin Islands (U.S.)vn — Vietnamvu — Vanuatuwf — Wallis and Futunaws — Samoaye — Yemenyt — Mayotteza — South Africazm — Zambiazw — Zimbabweafrican-union — African Unionarab-league — Arab Leagueeu — European Unionnato — NATOun — United Nationsus-ak — Alaskaus-al — Alabamaus-ar — Arkansasus-az — Arizonaus-ca — Californiaus-co — Coloradous-ct — Connecticutus-dc — District of Columbiaus-de — Delawareus-fl — Floridaus-ga — Georgiaus-hi — Hawaiius-ia — Iowaus-id — Idahous-il — Illinoisus-in — Indianaus-ks — Kansasus-ky — Kentuckyus-la — Louisianaus-ma — Massachusettsus-md — Marylandus-me — Maineus-mi — Michiganus-mn — Minnesotaus-mo — Missourius-mt — Montanaus-nc — North Carolinaus-nd — North Dakotaus-ne — Nebraskaus-nh — New Hampshireus-nj — New Jerseyus-nm — New Mexicous-nv — Nevadaus-ny — New Yorkus-oh — Ohious-ok — Oklahomaus-or — Oregonus-pa — Pennsylvaniaus-ri — Rhode Islandus-sc — South Carolinaus-sd — South Dakotaus-tn — Tennesseeus-tx — Texasus-ut — Utahus-va — Virginiaus-vt — Vermontus-wa — Washingtonus-wi — Wisconsinus-wv — West Virginiaus-wy — Wyomingmatter-flags/flags/xx) are pure server components — use freely in RSC, SSR, SSG.<Flag />, <DuoFlag />, <FallbackFlag /> are client components only because they load chunks with useEffect. On the server they render a correct-size placeholder, so there is no hydration mismatch or layout shift. Wrap interactive usage in a client component boundary as usual.sideEffects: false, ESM only, one module per flag.
| Usage | Cost |
|---|---|
import MA from 'matter-flags/flags/ma' | ~0.5kB gzip flag + ~1.4kB shared runtime (once) |
<Flag code="ma"> | same, code-split per flag |
Core (matter-flags) | ~6kB gzip, zero flags bundled |
Seal-heavy flags (some US states, up to ~50kB gzip) cost what their artwork costs — you only pay for flags you import. pnpm size enforces the budget in CI.
Every flag renders role="img" with aria-label (country/organization name, or your title), and a matching title tooltip. Purely decorative? Hide it from assistive tech: <span aria-hidden="true"><Flag … /></span>.
NOTICE. Single l source, SVGO-optimized.assets/orgs/SOURCES.json and assets/states/SOURCES.json.pnpm install
pnpm build:flags # regenerate src/flags + README.md code tables
pnpm typecheck
pnpm build
pnpm size
Edit
scripts/manual.template.md, notREADME.md— the code tables are generated byscripts/build-readme.mjs.
Docs site: pnpm --filter matter-flags-site dev → http://localhost:4321/.
MIT — Matter Development. Flag artwork remains under its original licenses (see NOTICE, assets/*/SOURCES.json).
FAQs
Tree-shakeable, zero-dependency React flag components. One flag = ~1kB.
The npm package matter-flags receives a total of 0 weekly downloads. As such, matter-flags popularity was classified as not popular.
We found that matter-flags demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Research
/Security News
Operators behind PolinRider used a compromised GitHub account to plant malware in four development versions of a Packagist package with 700,000+ downloads.
Security News
GitHub Actions now supports cache-mode, a least-privilege control on the Actions cache aimed at the cache poisoning technique behind recent compromises.
Company News
Allow myself to introduce... myself.