Flagcn

Made by ·

Flagcn is a source-owned shadcn registry for accessible flags. It ships a small React image primitive, a searchable picker, and one installable wrapper for every flag in the catalog. SVG assets use in 4:3 and 1:1 variants. PNG, WebP, and JPEG assets use . U.S. state SVGs and original-proportion SVGs use FlagCDN as a documented fallback.

What is included

@flagcn/flag: accessible, responsive SVG/PNG/WebP/JPEG primitive with 4:3 and square presentation.
@flagcn/flag-picker: searchable keyboard-friendly selector.
@flagcn/all: the core components, picker, catalog, and all 306 named flag wrappers.
@flagcn/<code>: 306 individually installable country, territory, subdivision, and organization wrappers.
A Vite + React landing page with package-manager install tabs and a complete filterable catalog.
Fumadocs-inspired documentation with grouped navigation, page outlines, copy actions, and AI-agent guidance.
Machine-readable /llms.txt, /llms-full.txt, /AGENTS.md, an RFC 9727 API catalog, OpenAPI, Markdown content negotiation, and registry JSON endpoints.
Registry generation, schema validation, unit tests, and a clean-consumer CLI install test.

Local development

Requirements: Node.js 20 or newer and pnpm 10 or newer.

The app follows shadcn preset b5dN5XYzA: Base UI, Lyra, Mist base color, teal theme, Tabler icons, and DM Sans. The site is dark-first with zero-radius geometry.

Build and verify

pnpm build regenerates every country wrapper, runs shadcn build, type-checks the app, and produces the static site. pnpm check additionally runs lint, unit tests, registry validation, and installs @flagcn/ae into a temporary clean consumer through the shadcn CLI.

After deployment, set REGISTRY_TEST_ORIGIN to the public origin and run pnpm test:install to repeat the clean-consumer test against the live registry.

Generated registry payloads live in public/r. Do not hand-edit the country wrappers or generated JSON; change the source data or generator and rebuild instead.

Use the registry

Flagcn is listed in the official shadcn Registry Directory. Install any item directly:

Older CLI snapshots can use this compatibility entry in components.json:

You can add the compatibility entry with the CLI:

The canonical directory entry is maintained in .

Component API

tsx

import { Flag } from "@/components/flags/flag"
export function MarketFlag() {  return (    <Flag      code="ae"      ratio="1x1"      width={40}      alt="United Arab Emirates"      className="ring-1 ring-border"      onLoad={() => console.log("loaded")}    />  )}

Flag forwards standard React image props such as className, style, onLoad, fetchPriority, and ref. Its own props are code, format, width, ratio, and decorative. Formats are svg, png, webp, and jpg. The default ratio is 4x3; use 1x1 for a square box that preserves the full flag or original when the official proportions matter.

@flagcn/all also generates a collision-safe barrel, so similarly named entries such as Georgia and the U.S. state of Georgia remain separately typed.

Configure for production

Set REGISTRY_URL to the final public origin when building.
Set VITE_GITHUB_URL when the public repository is ready.
Update the Pages origin in .env.example if you attach a custom domain.
If the brand or namespace changes, search for flagcn and update the registry generator, site config, docs, and install test together.
Deploy the dist directory to any static host. Preserve the SPA fallback while serving /r/*.json directly.

Example:

Deploy to Cloudflare Pages

Git deployment is the recommended production path:

Push the project to GitHub or GitLab.
In Cloudflare, open Workers & Pages, create a Pages project, and connect the repository.
Use pnpm build as the build command and dist as the output directory.
Set NODE_VERSION=22, REGISTRY_URL=https://flagcn.dev, and VITE_GITHUB_URL=https://github.com/shadi-almilhem/flagcn in the production environment.
After the first deployment, attach the custom domain from the Pages project's Custom domains tab.

For a manual deployment after pnpm build:

The included public/_headers applies registry CORS and security headers. public/_redirects preserves the React documentation routes, while public/404.html ensures that an invalid registry item returns an actual 404 response. Cloudflare copies all three files into dist during the Vite build.

Registry structure

text

registry.json                         source registry catalogscripts/generate-registry.mjs        wrapper and catalog generatorscripts/check-registry.mjs           built payload validatorscripts/test-registry-install.mjs    clean shadcn consumer testsrc/components/flags/                distributed component sourcesrc/components/flags/countries/      generated fixed-code wrapperspublic/r/                             generated installable JSONsrc/pages/                            documentation and catalog UIpublic/llms.txt                       concise AI-agent indexpublic/llms-full.txt                  complete machine-readable referencepublic/AGENTS.md                      consumer-agent operating instructions

Data and licensing

Original Flagcn source code is MIT licensed and distributed files carry an SPDX identifier. Country, territory, and organization SVGs are served from Flag Icons 7.5.0, which is MIT licensed and provides 4:3 and 1:1 variants. PNG, WebP, and JPEG assets come from Flagpedia's FlagCDN. Flagpedia states that its artwork is public domain and based on Wikimedia Commons files; see . U.S. state SVGs and original-proportion SVGs also use FlagCDN because Flag Icons does not provide those exact assets. See THIRD_PARTY_NOTICES.md [blocked] for the full boundary.

Public-domain artwork status does not override jurisdiction-specific rules governing national flags, seals, or official emblems. Applications are responsible for using official symbols appropriately in their markets.

Contributing

Read CONTRIBUTING.md [blocked] before opening a change. Security reports should follow SECURITY.md [blocked].