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 23 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
The compromise affects MemTensor's MemOS, an open source memory framework for large language models (LLMs) and AI agents. Both npm package @memtensor/memos-cloud-openclaw-plugin and the PyPI package MemoryOS are compromised. They drop cross-platform Go binaries that exfiltrate developer secrets.
Security News
Lovable’s OJ rewrites Vite’s dev server in Rust, reducing memory use and preview times as AI lowers the cost of open source reimplementation.
Security News
It has been one year since Shai-Hulud made its first appearance on npm.