Basic Usage

Import strategies

Choose the right approach based on your use case:

1. Named Imports

2. CircleFlag

3. DynamicFlag

1. Named Imports

Best for static flags.

Bundle impact: ~950 bytes per flag
Tree-shaking: ✅ Excellent
Loading: Synchronous, instant
Best for: Known flags at build time

Import only the flags you need from the main entry. Modern bundlers will automatically tree-shake unused exports:

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

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

When to use:

You know which flags you need at build time
Want synchronous rendering without loading states
Working offline or in restricted network environments

2. CircleFlag

Best for dynamic flags.

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

Load SVG flags from CDN on demand. Perfect for runtime-determined country codes:

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

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

Result: ~2 KB bundle impact, SVG flags loaded on demand from CDN

When to use:

Country codes determined at runtime (user input, API responses)
Want minimal bundle size
Can tolerate async loading with brief loading states
Have reliable CDN access

3. DynamicFlag

Loads all flags in a single bundle.

Bundle impact: ~600 KB
Tree-shaking: ❌ None
Loading: Synchronous, instant
Best for: CDN-restricted environments

Bundles ALL 400+ flag components. Only use when you absolutely need synchronous rendering of any flag:

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

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

When to use:

Offline-first applications with no CDN access
Need to render any flag synchronously
Bundle size constraints are relaxed

Naming convention

All flag components follow a consistent naming pattern:

Pattern

Components use the format Flag{ISO} where ISO is the uppercase country code.

Examples

FlagUs → United States
FlagCn → China
FlagGb → United Kingdom
FlagJp → Japan

Framework examples

The library works seamlessly with all modern React frameworks:

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

export default function Page() {
  return (
    <main>
      <h1>Country Flags</h1>
      <div className="flex gap-4">
        <FlagUs width={64} height={64} />
        <FlagCn width={64} height={64} />
      </div>
    </main>
  )
}

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

export default function Index() {
  return (
    <div>
      <h1>Country Flags</h1>
      <div className="flex gap-4">
        <FlagUs width={48} height={48} />
        <FlagCn width={48} height={48} />
      </div>
    </div>
  )
}

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

function App() {
  return (
    <>
      <h1>Country Flags</h1>
      <div className="flex gap-4">
        <FlagUs width={56} height={56} />
        <FlagCn width={56} height={56} />
      </div>
    </>
  )
}

export default App

Next steps

Bundle Size Optimization Compare bundle sizes and choose the best strategy

Styling Customize flag appearance with CSS and inline styles

Dynamic Flags Learn when to use CircleFlag vs DynamicFlag