Flagcn: React Flag Components & Picker for shadcn/ui

Flagcn is a React flag component registry for shadcn/ui that installs country, territory, subdivision, and organization flags as editable source files.

It currently includes an image primitive for rendering a single flag by code, a searchable flag picker, and 306 individually installable wrappers, one per country, territory, subdivision, and organization.

Features

• 306 named flag wrappers for countries, territories, organizations, and selected subdivisions.
• SVG, PNG, WebP, and JPEG assets with 4:3, 1:1, and original proportions.
• A dynamic Flag primitive for rendering flags from codes at runtime.
• Searchable flag and country pickers with keyboard interaction and controlled state.
• Typed country, language, currency, calling-code, and regional data.
• Country badges, flag avatars, phone input, language picker, and currency controls.
• Direct installation through the @flagcn namespace in the shadcn CLI.

Use Cases

• Checkout and shipping forms restrict country selection to the markets served by a store and submit the selected country code with the form.
• Market dashboards keep flag cells visually consistent across tables, cards, and region summaries with fixed 4:3 or square frames.
• International registration forms pair country selection with calling codes, phone formatting, and validation metadata.
• Language and currency settings combine recognizable regional artwork with explicit language or currency labels.

How To Use Flagcn

Choose The Registry Item

Choose the smallest item that matches your task:

Install Through shadcn/ui

pnpm dlx shadcn@latest add @flagcn/flag
pnpm dlx shadcn@latest add @flagcn/flag-picker
pnpm dlx shadcn@latest add @flagcn/country-picker
pnpm dlx shadcn@latest add @flagcn/phone-input
pnpm dlx shadcn@latest add @flagcn/ae
pnpm dlx shadcn@latest add @flagcn/all

Inspect registry items before installation when you need to check their files or dependencies:

pnpm dlx shadcn@latest view @flagcn/ae
pnpm dlx shadcn@latest search @flagcn -q "United Arab Emirates"
pnpm dlx shadcn@latest list @flagcn

Basic Flag Usage

Install @flagcn/flag when the flag code comes from application data:

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

Flag renders a native <img> element. The component builds its own image URL, dimensions, and responsive raster sources from the flag code and image settings.

Use A Named Flag Wrapper

A fixed flag does not need a runtime code prop. Install its registry entry and import the generated wrapper:

pnpm dlx shadcn@latest add @flagcn/ae

import { UnitedArabEmiratesFlag } from "@/components/flags/countries/ae"
export function RegionBadge() {
  return (
    <UnitedArabEmiratesFlag
      width={32}
      alt="Available in the United Arab Emirates"
    />
  )
}

Formats and Aspect Ratios

4x3 is the default frame. 1x1 creates a square frame. Both modes use contained image sizing, so the complete artwork stays visible inside the selected box. original keeps the source artwork proportions.

Raster images generate candidates from the requested width. Pass sizes when CSS changes the displayed image width across breakpoints:

<Flag
  code="br"
  format="webp"
  width={160}
  sizes="(max-width: 640px) 80px, 160px"
  alt="Brazil"
/>

Styling

The installed source lives inside the project, and the components use the project’s Tailwind and shadcn conventions. Standard className and style values remain available on Flag.

<Flag
  code="de"
  width={48}
  ratio="1x1"
  alt="Germany"
  className="rounded-md border shadow-sm"
/>

The rendered image exposes these data attributes for CSS selectors:

data-slot="flag"
data-code="de"
data-format="svg"
data-ratio="1x1"

Accessibility

Use context-specific alt text when the flag communicates information:

<Flag code="fr" alt="France" />

Mark the image as decorative when nearby visible text already communicates the same information:

<span className="inline-flex items-center gap-2">
  <Flag code="fr" width={24} decorative />
  France
</span>

Alternatives And Related Resources

• ISO-Compliant Country Dropdown & Phone Input Components for shadcn/ui
• Country & Region Select Components for shadcn/ui
• Add Phone Input with Country Validation to shadcn/ui