Dynamic Flags

When you need to render flags based on runtime data (user input, API responses, database values), you have two options:

Option 1: CircleFlag (Recommended)

Use CircleFlag for minimal bundle size with on-demand CDN loading:

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

export function CountryFlag({ code }: { code: string }) {
  return <CircleFlag countryCode={code} width={36} height={36} title="Country flag" />
}

Best for Most Cases

CircleFlag loads SVG flags from CDN on demand, adding only ~2 KB to your bundle while supporting all 400+ flags.

SVG props scope

CircleFlag renders a <div> wrapper with the fetched SVG inside. SVG-specific props (e.g. stroke, viewBox) will not apply through the wrapper; stick to sizing (width/height) and className/style for the wrapper, or use named imports/DynamicFlag when you need direct SVG props.

Backward Compatible API:

For compatibility with react-circle-flags, you can also use the code prop:

// Both work the same way
<CircleFlag countryCode="us" width={36} />
<CircleFlag code="us" width={36} />

Option 2: DynamicFlag

Use DynamicFlag when you need synchronous rendering and cannot use CDN:

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

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

Large Bundle Size

DynamicFlag bundles ALL 400+ flag components (~600 KB) in your bundle. Only use this if:

• You cannot access CDN in your environment
• You need synchronous, instant rendering without loading states
• Bundle size is not a primary concern

When to use it

User Input

Country selectors, forms, or settings where users choose their location.

API Responses

Data fetched from external APIs that include country codes.

Database Records

User profiles or records stored with country information.

Runtime Values

Any scenario where the country code is not known at build time.

Real-world example

With CircleFlag (Recommended)

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

interface User {
  name: string
  countryCode: string
}

export function UserProfile({ user }: { user: User }) {
  return (
    <div className="flex items-center gap-3">
      <CircleFlag
        countryCode={user.countryCode.toLowerCase()}
        width={32}
        height={32}
        title={`${user.name}'s country`}
      />
      <span>{user.name}</span>
    </div>
  )
}

With DynamicFlag

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

interface User {
  name: string
  countryCode: string
}

export function UserProfile({ user }: { user: User }) {
  return (
    <div className="flex items-center gap-3">
      <DynamicFlag
        code={user.countryCode.toLowerCase()}
        width={32}
        height={32}
        title={`${user.name}'s country`}
      />
      <span>{user.name}</span>
    </div>
  )
}

Bundle Size Comparison

CircleFlag (Best)

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

• Bundle impact: ~2 KB (component only)
• Loading: Async from CDN
• Tree-shaking: ✅ Perfect
• Best for: Minimal bundle size with dynamic flags

DynamicFlag

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

• Bundle impact: ~600 KB (all flags bundled)
• Loading: Synchronous, instant
• Tree-shaking: ❌ None
• Best for: CDN-restricted environments

Code Normalization

Both CircleFlag and DynamicFlag automatically convert country codes to lowercase, so "US" and "us" work identically.

Advanced: CircleFlag with Custom CDN

For better performance or region-specific optimization:

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

export function CountryFlag({ code }: { code: string }) {
  return (
    <CircleFlag
      countryCode={code}
      width={36}
      height={36}
      cdnUrl="https://custom-cdn.example.com/flags/"
    />
  )
}

Decision Tree

Need dynamic flags?
├─ Can use CDN? → ✅ Use CircleFlag (~2 KB)
└─ Cannot use CDN? → Use DynamicFlag (~600 KB)

Note: For flags known at build time, use named imports for best bundle size:

import { FlagUs, FlagCn } from '@sankyu/react-circle-flags'
// ~950 bytes per flag with tree-shaking

Next step

Bundle Size Learn about bundle size optimization and tree-shaking strategies