Migrate from react-circle-flags

Quick guide for migrating from react-circle-flags to @sankyu/react-circle-flags.

Why switch?

Bundle Size

Much smaller with tree-shaking (~950 bytes per imported flag vs. 200 KB+)

TypeScript

Full type definitions with autocomplete for 400+ flags

Offline-first

Inline SVG components with no external requests (works offline)

Migration (recommended): Named imports

Replace react-circle-flags runtime loader with tree-shakeable flag components.

import { FlagCn, FlagUs } from '@sankyu/react-circle-flags'

export function Header() {
  return (
    <div>
      <FlagUs width={35} height={35} />
      <FlagCn width={35} height={35} />
    </div>
  )
}

Notes

react-circle-flags uses string sizes like height="35". This library uses numbers: height={35}.
All flags accept standard SVG props (className, style, event handlers, etc.).

Runtime country codes

If country codes come from runtime data (API/user input), you have two offline-first options.

Option A: Finite set (named imports + map) — recommended

import { FlagCn, FlagGb, FlagUs } from '@sankyu/react-circle-flags'

const FLAGS = { cn: FlagCn, gb: FlagGb, us: FlagUs } as const

export function CountryFlag({ code }: { code: string }) {
  const normalized = code.toLowerCase()
  const Flag = FLAGS[normalized as keyof typeof FLAGS]
  return Flag ? <Flag width={32} height={32} /> : <span>{code.toUpperCase()}</span>
}

Option B: Any code (DynamicFlag) — bundles all flags

import { DynamicFlag } from '@sankyu/react-circle-flags'

export function CountryFlag({ code }: { code: string }) {
  return <DynamicFlag code={code} width={32} height={32} />
}

Bundle size comparison

Approach	Bundle Size	Network	Offline
`react-circle-flags`	~200 KB+	None	✅
Named imports (3 flags)	~2.8 KB	None	✅
DynamicFlag	~600 KB	None	✅

Migration steps

npm uninstall react-circle-flags
npm install @sankyu/react-circle-flags

pnpm remove react-circle-flags
pnpm add @sankyu/react-circle-flags

yarn remove react-circle-flags
yarn add @sankyu/react-circle-flags